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COURSE DESCRIPTION 
F15C PL/I Programming with Multics Subroutines 



Duration: Five Days 

• Intended For: Advanced Multics PL/I programmers who need to use Multics 

subroutines to perform I/O, manipulate files in the 
storage system, and/ or write commands and active 
functions. 



Synopsis: This course introduces the student to the system 

subroutine repertoire to include subroutines that: 
create, delete, develop pointers to, and return status 
information about storage system entities (hcs_); perform 
stream and record I/O to files and devices via I/O 
switches (iox_); enable command and active function 
procedures to properly interface to the standard command 
processing environment ( cu_) . Interactive workshops 
are included to reinforce the material presented. 

Objectives: Upon completion of this course, the student should be 
able to: write PL/I programs containing calls to system 
subroutines which: 

1. Create, destroy, and obtain status information on 
segments, directories, and links. 

2. Address and manipulate data directly in the virtual 
memory (without input/output statements). 

3. Interface directly with the Multics I/O System ( ioa_, 
iox_) . 

4. Implement "system standard" commands and active 
functions . 



Prerequisite^:: Advanced Multics PL/I Programming (F15B) or equivalent 
experience. 

Major Topics: Advanced Use of Based Variables 

Subroutine Interfaces to the Storage System 
and ACL 

Multics Implementation of Condition Handling 

The Multics I/O System 

Writing Commands and Active Functions 
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F15C TOPIC MAP 
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MORNING TOPICS 


AFTERNOON TOPICS 
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WELCOME/ ADMINISTRATION 
REVIEW OF PL/I ATTRIBUTES 
PL/I STORAGE MANAGEMENT 
WORKSHOP #1 


BASED STORAGE 
WORKSHOP #2 
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INTRODUCTION TO SUBROUTINES 
ADVANCED BASED VARIABLE USAGE 

WORKSHOP #3 


MULTICS CONDITION MECHANISM 
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THE MULTICS I/O SYSTEM 
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THE MULTICS iox_ SUBROUTINE ' 
THE MULTICS ioa_ SUBROUTINE 
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STORAGE SYSTEM SUBROUTINES 
WORKSHOP #7 


STORAGE SYSTEM SUBROUTINES 
(CONTINUED) 

WORKSHOP #8 
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REVIEW, QUESTIONS AND 

WORKSHOP COMPLETION 
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STUDENT BACKGROUND 
PL/I Programming with Multics Subroutines (F15C) 



NAME: PHONE: 

TITLE: 

COMPANY ADDRESS: 



MANAGER: OFFICE PHONE: 



INSTRUCTOR'S NAME: 



1. Do you meet the prerequisite as stated in the "Course Description" 
of the student text? If yes, check "a" or "b" . 
If no, check "c" or "d". 

a [ 3 Prerequisite satisfied by attending course indicated in "Course 
Description" . 

b [ ] Meet prerequisite by equivalent experience (explain briefly) 



c [ 3 Elected or instructed to attend course anyway, 
d [ 3 Was not aware of prerequisite. 

2. What related Honeywell courses have you attended? Furnish dates 
and instructors if possible. 



(PLEASE TURN OVER) 
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STUDENT BACKGROUND 
PL/I Programming with Multics Subroutines (F15C) 



3. Check the boxes for which you 
be other than Honeywell's) 

[ ] PL1 C ] COBOL 

[ ] JCL C ] OPERATIONS 

C ] NPS [ ] GRTS 



have any related experience. (May 

[ ] FORTRAN [ ] ASSEMBLY 

C -] GCOS C 3 MULTICS 

C 3 CP6 C 3 OTHER 



4. Detail any experience you have had which is related to the 
material in this course. 



5. Objectives for attending this course (May check more than one). 

[ 3 Require information to provide support for a system 

[ 3 To maintain an awareness of this product 

C 3 To evaluate or compare its potentials 

[ 3 Required to use or implement 

[ 3 Need update from a previous release 

C 3 Require a refresher 

C 3 Other ; 
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HONEYWELL MARKETING EDUCATION 
COURSE AND INSTRUCTOR EVALUATION FORM 



INSTRUCTOR ______^______ 

COURSE ._____-____»___ 

START DATE _______________ 

LOCATION _■________«___ 

STUDENT NAME (OPTIONAL) 



In the interest of developing training courses of high quality, 
and then improving on that base, we would like you to complete 
this questionnaire. Your information will aid us in making 
future revisions and improvements to this course. Both the 
instructor and his/her manager will review these responses. 

Please complete the form and return it to the instructor 
upon the completion of the course. In questions 1 through 
14, check the appropriate box and feel free to include additional 
comments. Attach additional sheets if you need more room 
for comments. Be objective and 'concrete' in your comments 
— be critical when criticism is appropriate. 
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TOPIC I 
Review of PL/I Attributes 



Page 

Classification of Attributes 1-1 

Usage Examples of Selected Attributes 1-2 

Aggregate Descriptors 1-7 
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Topic I REVIEW OF PL/1 ATTRIBUTES Topic I 

OBJECTIVES: 

Upon completion of this topic? students should be able to£ 

1. Declare variables in PL/1 using full ranse of variable 
attributes. 

2. Determine which instance of a variable is being referenced at 
any given point in a program. 

3. Manipulate storage aggregates (arrays and structures). 

4. Write and use external procedures. 

5. Set up the proper entry declarations to use external 
p rocedures . 



Multics 
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CLASSIFICATION OF ATTRIBUTES 



• A REVIEW LIST OF ATTRIBUTES. STARRED ATTRIBUTES ARE COVERED IN 
DETAIL IN TOPICS 2, 3 AND 4. THIS CHAPTER PRESENTS USAGE EXAMPLES 
TO REVIEW/ CLARIFY SOME OF THE NON-STARRED ATTRIBUTES 



storage description 
storage type 
data type 

computational 
arithmetic 

mode : real complex 
scale : fixed float 
base : binary decimal 
precision : precision( p,q) 
string 

string type : character(n) bit(n) picture"ps M 
variability : varying nonvarying 
non - computational 
address 

statement : label entry format 
data 

locator : pointer* offset* 
file : file 
area : area(n)* 
aggregate type 

array : dimensionC bp, . . . ) 
structure : structure member 
alignment : aligned unaligned 
management class 
storage class 

allocation : automatic static controlled* based(lq)* 
sharing : based(lq)* defined(r)* position(i)* parameter 
scope : internal external 
category : variable constant 
initial : initial (x,...) 
usage description 

entry : entry( d, . . . ) returnsC d , . . . ) options( variable) 
offset : offset(a)* 
f ile""c*onstant 

operation : input output update 
organization 

stream : stream print environmentC interactive) 
record : record sequential direct keyed 
environmentC stringvalue) 

non - valued names 

compile time : like r 

intrinsic names: builtin condition* 



Not To Be Reproduced 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 
ARITHMETIC DATA TYPES 

Q del x real fixed binary precision (17,0) aligned; 
fl del x; /* SAME AS PREVIOUS DECLARATION */ 

Q del salary float decimal (6); 

STRING DATA TYPES 

0 del string_1 char(4) init ("ABC"); 

0 del string 2 char(4) varying init ("ABC"); 



stringy 1 



string 2 





, ■ 


C 






n 






..011 




A 


B - 


C 


/ / / 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• STATEMENT LABEL PREFIX (DECLARED BY USAGE, NOT IN FORMAL DECLARATION) 



Q continue_1 : x = x + 1 ; 



/* label internal constant */ 



0 output_1 : format ( a(9) ,f (6 ,2)) ; /* format internal constant */ 



D prog_ 1 : proc; 



/* entry constant */ 



Q alternate: entry (a,b); 



/* entry constant */ 



• ALIGNMENT 



fl del string char(4) aligned; /* DEFAULT IS unaligned */ 



del number fixed bin unaligned; /* DEFAULT IS aligned */ 



• STATIC VS. AUTOMATIC 



0 del a init(O); 

del b init(O) static; 



/* automatic BY DEFAULT V 



a = a + 1 ; 
b = b + 1; 
put skip list ( a ,b) ; 



Not To Be Reproduced 



1-3 



F15C 



USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• AGGREGATES 



fl ARRAY 



0 del array_1 (iO); 

del array~2 (-6:4); 

del array~3 (10,3); 

del array_ 4 dimension (5); 



D STRUCTURE 

fl del 01 x structure, 

02 y char(8) member, 

02 z fixed bin(35) member; 

fl del 01 x, 02 y char(8), 02 z fixed bin(35); 

fl LIKE ATTRIBUTE 

fl del 1 record_1 , 

2 employee info, 
3 name cKar( 10) , 
3 salary fixed dec(10,2); 

Q del 1 record_2 like record_1 ; 

II del 1 employee like record_1 .employee^ info .name; 



• PARAMETER 



sub_ 1 : proc ( a .b) : 

del a char(3) parameter; 

del b char(6); /* parameter ATTRIBUTE USUALLY OMITTED */ 



Not To Be Reproduced 
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# USAGE EXAMPLES OF SELECTED ATTRIBUTES 



$ SCOPE OF VARIABLES 



A: proc; /* SOURCE SEGMENT A.pU */' 

del x external; # £kHc bV ^mjj\t^/ 
del y; / 



B: proc; 
del x; 



end B; 
end A; 



C: proc; /* SOURCE SEGMENT C.pll */ 

del x external; 

end C; 

D: proc; /* SOURCE SEGMENT D.pll */ 

del x; 

del y; 

end D; 



Not To Be Reproduced 
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USAGE EXAMPLES OF SELECTED ATTRIBUTES 



• VARIABLE VS. CONSTANT 



D del x internal static init (125) options (constant); 
del (filej, file_2) file; 
del fiie_ out f ile~variabie; 

file_out = file_2; 

put file (file_out) list ("Test line"); 



D TYPES OF IDENTIFIERS THAT ARE USUALLY USED AS CONSTANTS, BUT MAY 
BE DECLARED AND USED AS VARIABLES: label, entry, format, file 



• INITIALIZATION 



0 del array 1(5) init(1 ,2,3,4,5); 

del array~2(5) initd ,2,(3)*); /* LAST 3 ELEMENTS UNDEFINED */ 
del array"3(3,2) init( 1 ,2,3,4,5,6) ; 



• ENVIRONMENT ATTRIBUTES 



D open file (sysprint) stream output environment (interactive); 

put list ("line 1"); /♦ LINEFEED ADDED AT END AUTOMATICALLY */ 
put list ( "line 2") ; 



Q del line char(150) varying; 

uv>i o o i ^euu i a j. j. c , 

open file ( stream_ file) environment ( stringvalue) record input 
title ( "record^ stream^ user_input" ) ; 

read file ( stream_file) into (line); 

/* MAKES POSSIBLE TAKING ENTIRE LINE FROM TERMINAL WITH EMBEDDED 
BLANKS WITHOUT USING QUOTES */ 

Not To Be Reproduced 1-6 F15C 



AGGREGATE DESCRIPTORS 



• DESCRIPTORS DESCRIBE THE DATA TYPE AND LAYOUT OF AN IDENTIFIER WITHOUT 
REFERENCE TO ANY VARIABLE NAMES OR IDENTIFIERS 



• DESCRIPTORS ARE USED IN "PARAMETER DESCRIPTOR" LISTS, AND IN "RETURNS 
DESCRIPTOR" LISTS 



0 EXAMPLES 



D declare foo$bar entry (fixed bin, ptr , char(*)); 



II declare how_many entry (fixed bin) returns (fixed dec(3,0)); 



Not To Be Reproduced 
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AGGREGATE DESCRIPTORS 



• DESCRIPTORS ARE FORMED FOR AGGREGATES AS FOLLOWS: 

0 ARRAY DESCRIPTORS 

0 ARE DERIVED BY ELIMINATING THE IDENTIFIER FROM THE DECLARATION 

Q THE ARRAY BOUNDS MAY BE PRECEDED BY THE 'dimension' OR 'dim' 
KEYWORD, OR THE KEYWORD MAY BE OMITTED IF THE ARRAY BOUNDS 
PRECEDE THE DATA TYPE 

0 EXAMPLES 

I del X(12,3) fixed dec(7); 

0 del getJC entry ((12,3) fixed dec(7)); 

Q del returnJC entryO returns (dim(12,3) fixed dec(7)); 

Q STRUCTURE DESCRIPTORS 

D ARE DERIVED FROM THE DECLARATION AS FOLLOWS: 
0 ELIMINATING ALL IDENTIFIERS 
0 NORMALIZING THE LEVEL NUMBERS 

0 THE KEYWORDS 'structure' AND 'member' MAY BE OMITTED FROM THE 
DESCRIPTORS 



Not To Be Reproduced 



1-8 



F15C 



AGGREGATE DESCRIPTORS 



0 EXAMPLE 



del 1 A aligned, 

2 C(3) fixed bin, 
2 F ptr; 

D del get_A entry (1 structure aligned, 2 dim(3) fixed bin 

member, 2 ptr member); 

Q del returns A entry () returns (1 aligned, 2 (3) fixed bin, 

2 ptr); 

0 del get_A entry (1 like A); 

D del returns_A entry () returns (1 like A); 



Not To Be Reproduced 



1-9 

(End Of Topic) 



F15C 



Considering the stated objectives of this course, rate the overall 
length of the course. 

CAN'T TOO ABOUT TOO 

JUDGE SHORT RIGHT LONG 

1 0 I i 1 i 2 j I I 4 I g I 6 I 7 I 8 I Q I 

COMMENTS 



Considering the objectives, rate the technical level at which the 
course was taught. 

NOT 

CAN'T TECH ABOUT TOO 

JUDGE ENOUGH RIGHT TECH 

IT! l i 1 2 I 5 I 4 1 5 I S I 7 1 A I T1 

COMMENTS 



Considering the objectives, rate the emphasis placed on the more 
important topics. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

1—8—1 I 1 I 2 I I I 4 I g I I I 7 I A I Q I 

COMMENTS 



« 



Rate the sequence in which the topics were presented. 



CAN'T 

JUDGE POOR GOOD EXCELLENT 

CO I 1 I I I 3 I I I 5 1 1 1 Z ! 1 1 S ! 

COMMENTS 
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Rate the format and quality of the learning materials (slides, 
student handbooks, supplementary handouts, etc.). 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

CO I 1 O * 3 I 1 * I \ I 1 2 i B 

COMMENTS 



Rate the amount of time given for the completion of the workshops. 

TOO TOO 
CAN'T LITTLE ABOUT MUCH 

JUDGE TIME RIGHT TIME 

I o I I 1 I 2 I ^ I 1* I 5 I 6 I 7 I A I T-1 

COMMENTS 



Rate the workshops' ability to relate back to and reinforce the 
material presented. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

I — o — 1 1 1 I 3 I \ I I I \ I 6 I 7 I I I a 1 

COMMENTS 



Rate the physical condition of the classroom (space available, 
temperature, lighting, etc.). 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

I Q | I 1 I 2 I j I k I 5 I & I 7 I A i 0 — 1 

COMMENTS 
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9. Rate the physical condition of the lab or workshop room, (systems 
configuration, space available, learning tools, terminals, tables, 
etc .) . 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

nn i 1 i 2 I g i k i g 1 & 1 7 ' B ' a 3 

COMMENTS 



10. Rate your instructor 1 s demonstrated knowledge of the course material . 



CAN'T 

JUDGE POOR GOOD EXCELLENT 

I 0 I Ill2l3|ill5lfll7l6lql 

COMMENTS 



11. Rate your instructor's ability to convey the technical aspects of 
the various topics. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

I 0 I Il>2l^|itlql6l7l5lql 

COMMENTS 



12. Rate the classroom and workshop assistance given you by your 
instructor . 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

j O I |i i2!^!4*?86l7!5i9! 

COMMENTS 
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13. 



Rate the instructors ability to create an environment in which 
you felt free to ask questions. 



CAN'T 

JUDGE POOR GOOD EXCELLENT 

I 0 1 11 I2t^i4t5lfai7iat9l 

COMMENTS 



14. Rate the relevance of the skills learned in the course with respect 
to your job or further training. 

CAN'T 

JUDGE POOR GOOD EXCELLENT 

1 0 1 q I 

COMMENTS 



15. What did you like most about this course? 



16. What did you like least about this course? 
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17. Other comments please: 



18. Of the following job categories, check the ones which most nearly 
represent the bulk of your experience, and to the right of your 
responses indicate the number of years you have acted in that 
capacity. 



Applications Programmer. . . . years 

Field Engineering Analyst. . . years 

Manager years 

Marketing Analyst years 

Salesperson, ......... years 

Secretary years 

Systems Analyst years 

Systems Programmer years 

Other years 



Please give "other" title 
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TOPIC II 
PL/I Storage Management 
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Topic II PL/1 STORAGE MANAGEMENT Topic II 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1. Allocate and free controlled variables to implement a stack 
or a variable-extent data item such as a string or array. 

2. Use defined variables to chanse the interpretation of a 
particular area of storase. 

3. Manipulate cross-sections of arrays usins "isub"-def ined 
variables . 



Mul ti cs 
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DECLARING PL/I VARIABLES 



• THE DECLARATION OF AN IDENTIFIER IS USUALLY DIVIDED INTO TWO PARTS 

0 THE STORAGE TYPE 

0 DESCRIBES THE TYPE OF VALUES WHICH CAN BE ACCOMMODATED 

Q DESCRIBES THE AMOUNT AND INTERPRETATION OF STORAGE GENERATED 

C THE STORAGE MANAGEMENT CLASS 

0 SPECIFIES VARIOUS INFORMATION ABOUT THE HANDLING OF THE STORAGE 
GENERATED FOR THE IDENTIFIER INCLUDING 

D THE ALLOCATION AND FREEING MECHANISM TO BE USED 

Q THE LOCATION OF THE STORAGE TO BE GENERATED 

!1 INITIALIZATION OF STORAGE 

0 AN EXAMPLE 

0 del x real fixed binary(1Q,Q) automatic variable init(5); 
D 'real fixed binary( 10 , 0) » IS THE STORAGE TYPE 
D 'automatic variable init(5) f IS THE STORAGE MANAGEMENT CLASS 



Not To Be Reproduced 
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DEFINING THE PL/I STORAGE MANAGEMENT CLASS 

• FOUR ATTRIBUTES SPECIFY THE STORAGE MANAGEMENT CLASS 

D THE 'usage category 1 ATTRIBUTE 

0 DESCRIBES HOW THE STORAGE IS USED 

Q VALUES ARE 'variable 1 AND 'constant' 

0 MOST OFTEN, THE USAGE CATEGORY ATTRIBUTE IS OMITTED 

fl THE 'scope' ATTRIBUTE 

0 PARTIALLY DETERMINES THE REGION IN WHICH THE STORAGE IS ALLOCATED 
Q AFFECTS THE ACCESSIBILITY OF THE IDENTIFIER 
0 VALUES ARE 'internal' AND 'external' 

Q THE 'storage class' ATTRIBUTE 

0 SELECTS THE MECHANISM TO BE USED FOR THE ALLOCATION AND FREEING 
OF THE STORAGE GENERATED 

4 

0 VALUES ARE 'automatic', 'static', 'controlled', 'based', 
'defined' AND 'parameter 5 

0 THE 'initial value' ATTRIBUTE 

0 WHEN PRESENT, SPECIFIES A VALUE TO BE ASSIGNED TO THE IDENTIFIER 
WHEN IT IS ALLOCATED 

B VALUE IS 'initial (value list)' 



Not To Be Reproduced 
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DEFINING THE PL/I STORAGE MANAGEMENT CLASS 
ABBREVIATIONS AND DEFAULTS 



• VALID ABBREVIATIONS FOR STORAGE MANAGEMENT ATTRIBUTES 



ATTRIBUTE 

internal 

external 

automatic 

controlled 

defined 

parameter 

initial 



ABBREVIATION 

int 

ext 

auto 

ctl 

def 

pa ram 

init 



• STORAGE MANAGEMENT DEFAULT VALUES 



OMITTED ATTRIBUTE 



DEFAULT VALUE 



usage category 



* variable 1 

( exception : 1 constant * if the data 
type is 'entry* or 'file') 



scope 



* internal 1 

( exception :' external ' if the data 
type is 'entry 1 or 'file') 



storage class 



' automatic' 

(exception: 'static* if the 
•external 1 attribute is 
present or implied) 



D NOTE: THE DEFAULTS APPLY TO IDENTIFIERS DECLARED IN A FORMAL 
DECLARATION STATEMENT. FOR EXAMPLE: 



D A LABEL FORMALLY DECLARED IS A variable BY DEFAULT 



0 A LABEL DECLARED BY USAGE AS A LABEL PREFIX IS A constant 



Not To Be Reproduced 
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'controlled' STORAGE CLASS 



CHARACTERISTICS 



• 'controlled' STORAGE ALLOWS THE PROGRAMMER TO CONTROL THE GENERATION 
OF STORAGE FOR A VARIABLE 



0 IT IS DRIVEN BY EXPLICIT PROGRAM STATEMENTS 



0 STORAGE IS ALLOCATED BY THE 'allocate' STATEMENT, AND FREED BY 
THE 'free' STATEMENT 



0 A 'controlled' VARIABLE IS THEREFORE AVAILABLE FOR WHATEVER PORTION 
OF EXECUTION OF THE PROGRAM THE PROGRAMMER DESIRES 



0 A SMALL CONTROL BLOCK ASSOCIATED WITH THE 'controlled 1 VARIABLE 
IS USED TO LOCATE ITS CURRENTLY ALLOCATED STORAGE 



D 'controlled' VARIABLES CAN BE "STACKED" 



THEY CAN HAVE EITHER 'internal* OR 'external' SCOPE (internal IS 
THE DEFAULT) 



Not To Be Reproduced 
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'controlled* STORAGE CLASS 
ALLOCATION AND FREEING 

• A 'controlled 1 VARIABLE IS ALLOCATED BY EXECUTION OF THE 'allocate' 
STATEMENT 

D allocate id ; 

0 alloc id1 , id2, idN ; 

• A 'controlled' VARIABLE IS FREED BY THE EXECUTION OF THE 'free' 
STATEMENT 

0 free id ; 

fl free id1 , id2 1 idN ; 



Not To Be Reproduced 
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'controlled 1 STORAGE CLASS 
STACKING 'controlled' VARIABLES 



• PL/I ALLOWS US TO ALLOCATE A 'controlled' VARIABLE MORE THAN ONCE 
BEFORE FREEING ITS STORAGE 



II THE HISTORY OF ALLOCATIONS FOR EACH VARIABLE IS MAINTAINED ON A 
STACK SO THAT: 



II EACH 'allocate' STATEMENT LEAVES EARLIER ALLOCATIONS OF THAT 
VARIABLE UNDISTURBED 



0 A 'free' STATEMENT FREES THE MOST RECENTLY ALLOCATED SPACE 
FOR THAT VARIABLE 



0 EACH TIME THE VARIABLE IS REFERENCED, THE ONE "ON THE TOP OF 
THE STACK" IS ACCESSED (MOST RECENTLY ALLOCATED BUT NOT FREED) 



0 EXAMPLE 



P1: 


proc; 




del 


x float bin controlled; 




. . . (Computation 


#1) 




allocate x; 
x = 10; 

. . . (Computation 


#2) 




allocate x; 
x s 20; 

. . . (Computation 


#3) 




free x; 

... (Computation 


#4) 


end ; 


free x; 

. . . (Computation 


#5) 



Not To Be Reproduced 2-6 F15C 



'controlled' STORAGE CLASS 



VARIABLE EXPRESSIONS IN ATTRIBUTES 



• WHEN A 'controlled' VARIABLE IS ALLOCATED, ANY EXTENT EXPRESSIONS 
AND INITIAL VALUE EXPRESSIONS ARE EVALUATED 



0 EXTENTS ARE ARRAY BOUNDS, MAXIMUM STRING LENGTH, OR AREA SIZE 



0 EXTENTS MUST BE SET BEFORE THE EXECUTION OF AN 'allocate' STATEMENT 



0 EXTENTS ARE SAVED IN A SYSTEM TEMPORARY 



0 EXAMPLE 



P1 : proc; 

del n fixed bin init(O); 

del A(n+2) float bin controlled init( ( n+2 )0 ) ; 



n = 2; 
allocate A; 

n = 0; /*HAS NO EFFECT ON EXTENT*/ 

put skip list (A); 
free A; 



Not To Be Reproduced 
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'controlled 1 STORAGE CLASS 
GUIDELINES FOR USING Controlled 1 STORAGE 



• 'controlled' STORAGE IS GENERALLY MORE EXPENSIVE THAN THE BUILT-IN 
STORAGE MANAGEMENT MECHANISM OF AUTOMATIC OR STATIC STORAGE CLASSES 



• POSSIBLE APPLICATIONS: 



D WHEN A STACK OF VARIABLES IS NEEDED (THIS ALLOWS A PROGRAM WHICH 
USES STATIC VARIABLES TO BECOME REENTRANT BY REPLACING STATIC 
VARIABLES WITH 'controlled' VARIABLES) 



0 WHEN AN EXTERNAL VARIABLE MUST HAVE VARIABLE EXTENTS ('based' 
VARIABLES, WHICH COULD HAVE VARIABLE EXTENTS, CANNOT HAVE 'external' 
SCOPE) 



0 WHEN CONTROLLING THE AMOUNT OF STORAGE REQUIRED FOR A PROGRAM 
BECOMES CRITICAL 
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'controlled' STORAGE CLASS 
GUIDELINES FOR USING 'controlled' STORAGE 



• NOTE: PROGRAMS USING 'controlled' VARIABLES SHOULD PROVIDE AN 'on 
unit' FOR THE 'cleanup' CONDITION IN ORDER TO FREE ANY ALLOCATED 
STORAGE 



D THE 'allocation' BUILTIN FUNCTION RETURNS (IN A fixed bin(17)) 
THE CURRENT ALLOCATION DEPTH OF STORAGE FOR A 'controlled' VARIABLE 



0 EXAMPLE 



del cleanup condition; 
del x controlled; 

on cleanup begin; 

do i s 1 to allocation ( x) ; 

free x; 
end; 

end; 
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'defined' STORAGE CLASS 



CHARACTERISTICS 



• A 'defined' VARIABLE IS USED TO ASSOCIATE A NEW NAME WITH AN EXISTING 
VARIABLE OR PART OF AN EXISTING VARIABLE 



• IT SUPPLIES A POTENTIALLY DIFFERENT INTERPRETATION (REDEFINITION) 
OF AN EXISTING GENERATION OF STORAGE 



D IT MUST HAVE THE SAME DATA TYPE AS THE PART OF THE BASE VARIABLE 
BEING REDEFINED (EXAMPLE: A BIT STRING CANNOT BE 'defined' ON A 
CHARACTER STRING) 



0 IT ALWAYS HAS 'internal' SCOPE 



0 SINCE IT NEVER HAS STORAGE ALLOCATED FOR IT, A 'defined' VARIABLE 
CANNOT HAVE AN 'initial' ATTRIBUTE 



• NOTE: USE OF 'defined' VARIABLES IS NOT THE SOLE MEANS OF 
"REDEFINITION" OF VARIABLES ('based' VARIABLES WILL BE DISCUSSED 
LATER) 
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'defined* STORAGE CLASS 
CHARACTERISTICS 

• THE 'defined* ATTRIBUTE CONSISTS OF THE KEYWORD 'defined* FOLLOWED 
BY A REFERENCE TO A BASE VARIABLE 

• THERE ARE THREE WAYS TO USE 'defined* VARIABLES: 
I SIMPLE DEFINING 

1 STRING OVERLAY DEFINING 
S 'isub' DEFINING 
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'defined' STORAGE CLASS 



SIMPLE DEFINING 



EACH SCALER IN THE 'defined' VARIABLE AND THE CORRESPONDING SCALER 
IN THE BASE VARIABLE HAVE IDENTICAL STORAGE TYPES 



B EXAMPLE 1 



del array(5,5) char(4); 

del same_ array(5 , 5) char(4) defined array; 

del vector_1(5) char(4) defined array; 

del vector~"2(5) char(4) defined array(2,1); 



0 EXAMPLE 2 



del 1 a, 

2 b(n) , 

3 c float bin, 
3 d float bin, 

2 e ehar(6); 

del x float def ined( a.b( i-2 ) .d) ; 

del Y(n) float def ined( a .b( *) .d) ; 

del 1 z def ined( a.b( j) ) , 
2 z1 float bin, 
2 z2 float bin; 



# NOTE: THE BASE VARIABLE MAY NOT BE A 'defined' VARIABLE OR A NAMED 
CONSTANT 
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'defined* STORAGE CLASS 



STRING OVERLAY DEFINING 



• A STRING 'defined 1 VARIABLE IS MAPPED ONTO ALL OR PART OF THE STORAGE 
OF A STRING BASE VARIABLE 



5 VALID FOR ALL STRING TYPES AS LONG AS THEY ARE 'nonvarying unaligned' 



0 MUST MATCH BITS ONTO BITS OR CHARACTERS ONTO CHARACTERS 



0 PICTURED STRINGS CAN BE USED AS THE BASE VARIABLE, A FACT THAT 
PROVIDES 'defined' STORAGE ONE OF ITS MOST POWERFUL FACILITIES 

D EXAMPLE 

del a pic "999v.999es99"; 

del exponent char (3) defined (a) position (9); 

D THE 'position' OR 'pos' ATTRIBUTE CAN BE USED TO START THE 'defined' 
VARIABLE AT SOME BIT OR CHARACTER POSITION OTHER THAN THE FIRST 
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'defined' STORAGE CLASS 



STRING OVERLAY DEFINING 



D EXAMPLES 



del A(5) char(2) unal; 
del B char(8) def(A); 
del 1 C def(A), 

2 X char(5) unal, 

2 Y char(5) unal; 
del D char(5) def(A) pos(6); 
del E char(5) def(A(2)) pos(2); 



A(1) A(2) A{3) A(4) A(5) 



C.X 



C.Y 



3C 



Not To Be Reproduced 



2-14 



F15C 



'defined' STORAGE CLASS 



' isub' DEFINING 



• A FACILITY OF PL/I WHICH ALLOWS A 'defined' ARRAY TO MAP ONTO A 
BASE ARRAY IN A SPECIALIZED MANNER 



II THE VALUE OF THE 'isub' REFERS TO THE SUBSCRIPT OF THE DEFINED 
ARRAY, NOT THE BASE ARRAY 



I EXAMPLE 

del AC3,4) float bin; 

del Q(3) float bin defined A(1sub,4); 

del TRANS(4,3) float bin def ined( A(2sub , 1sub) ) ; 

Q(1) — > AO, 4) 

Q(2) — > A(2,4) 

Q(3) — > A(3,4) 



fl THE ARRAY 'Q' DEFINES THE FOURTH COLUMN OF 'A' 



fl THE ARRAY 'TRANS' REPRESENTS THE TRANSPOSE OF ARRAY 'A' 



fl IT REPRESENTS AN INTERPRETATION OF 'A' STORED IN COLUMN-MAJOR 
ORDER INSTEAD OF ROW-MAJOR ORDER 



II THIS CAN BE USEFUL FOR PASSING ARRAY ARGUMENTS FROM FORTRAN 
TO PL/I PROGRAMS AND VICE VERSA 
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'defined* STORAGE CLASS 



• isub' DEFINING 



0 CONSIDER A PL/1 2X2 ARRAY: 

AC 1 , 1) = 1 A(1,2) = 2 

A(2,1) = 3 A(2,2) = 4 

5 PL/1 WOULD STORE IT IN MEMORY IN ROW MAJOR ORDER 



1 


2 


3 


4 



fl FORTRAN WOULD, HOWEVER, STORE IT IN COLUMN MAJOR ORDER 



1 



mn 

lRE 



WHERE FORTRAN EXPECTS TO FIND A(2,1) 
PL/I MUST THEREFORE PASS FORTRAN A TRANSPOSE! 



del A(2,'2) fixed bin; 
del transpose A (2,2) fixed bin 
deTined A(2sub , 1sub) ; 



call fortran_prog ( transpose^ A) ; 
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•defined* STORAGE CLASS 



GUIDELINES FOR USING 'defined 1 STORAGE 



• 'defined' STORAGE MANAGEMENT IS "IN COMPETITION" WITH 'based' STORAGE 
MANAGEMENT 



1 'based' STORAGE MANAGEMENT IS MUCH MORE GENERAL 



D FOR MULTICS, 'based' IS GENERALLY PREFERRED OVER 'defined' STORAGE 
MANAGEMENT 



• USUALLY USED ONLY FOR THE ONE UNIQUE FEATURE PROVIDED — 'isub' 
DEFINING 



YOU ARE NOW READY FOR WORKSHOP 
#1 
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TOPIC III 
'based* Storage 
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Topic III BASED STORAGE Topic III 

OBJECTIVES: 

Upon completion of this topic? students should be able to! 

1. Allocate and free based variables in the same manner as 
controlled variables. 

2. Differentiate between packed and unpacked pointers. 

3. Use builtin functions to manipulate locator variables 
(pointers and offsets). 

4. Use based variables to redefine the interpretation of a 
particular area of storase. 

5. Use the "refer" option to implement self-def inins data. 

6. Manipulate areas. 



Multics 
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CHARACTERISTICS OF 'based' STORAGE 

• ADVANCED AND POWERFUL STORAGE MANAGEMENT TECHNIQUE HAVING THREE MAJOR 
APPLICATIONS 

D EXPLICITLY ALLOCATING AND FREEING SPACE MUCH LIKE CONTROLLED STORAGE 

0 EQUIVALENCING TO OR OVERLAYING A TEMPLATE UPON THE STORAGE GENERATED 
FOR SOME OTHER VARIABLE, MUCH LIKE DEFINED STORAGE 

1 ACCESSING A SEGMENT IN THE VIRTUAL MEMORY DIRECTLY, THUS ENABLING 
I/O TO A SEGMENT WITHOUT USING I/O STATEMENTS 

• THE SCOPE OF A 'based' VARIABLE IS ALWAYS 'internal' 

• THE DECLARATION OF A 'based' VARIABLE DESIGNATES ONLY THE DATA TYPE 
AND STORAGE TYPE ATTRIBUTE VALUES FOR THAT VARIABLE 

I IT DOES NOT DESIGNATE THE LOCATION OF THE VARIABLE 

II HENCE, EVERY REFERENCE TO A 'based' VARIABLE MUST BE QUALIFIED 
WITH A LOCATOR VALUE 

II LOCATOR VALUES CAN BE 'pointer' OR 'offset' VALUES 
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THE ; based 1 ATTRIBUTE 

• A • based 1 VARIABLE IS DECLARED WITH THE KEYWORD ■ based 1 OPTIONALLY 
FOLLOWED BY A PARENTHESIZED LOCATOR VARIABLE 

I del x fixed bin based; 

I EVERY REFERENCE TO 'x' MUST BE QUALIFIED BY A LOCATOR VARIABLE 

Q del x fixed bin based(p); 
del p pointer; 

I THE LOCATOR VARIABLE 'p* IS IMPLICITLY ASSOCIATED WITH 'x' 

0 EXPLICIT LOCATOR QUALIFICATION IS NOT NECESSARY (BUT IS 
RECOMMENDED) 

• EVERY 'based* VARIABLE REFERENCE MUST BE QUALIFIED BY A LOCATOR 
VALUE, EITHER: 

II EXPLICITLY (USING THE -> OPERATOR) 

"fl OR IMPLICITLY (IF THE VARIABLE WAS DECLARED WITH THE 1 based (locref) ' 
ATTRIBUTE) 
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THE 'based* ATTRIBUTE 



0 EXAMPLE (EXPLICITLY QUALIFIED) 



del A dec(5,2) based init(O); 
del p pointer; 
del sysprint file; 

• • • 

allocate A set( p) ; 

P->a'=*5; 

• • • 

put list (p->A); 

• • • 
free p->A; 



fl EXAMPLE (IMPLICITLY QUALIFIED) 



del n fixed bin; 

del S char(n+2) based ( beta) ; 

del beta pointer; 

• • • 
n = 4; 
allocate S; 

• « • 

S = "abedef"; 

• • • 

free S; 
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EXPLICITLY ALLOCATED 'based 1 VARIABLES 



• JUST AS IN THE CASE OF 'controlled' VARIABLES, BASED VARIABLES MAY 
BE EXPLICITLY ALLOCATED AND FREED 

Q THE 'allocate' AND 'free' ARE USED 



• 'based' VARIABLES MAY BE ALLOCATED IN TWO DIFFERENT WAYS: 

II USING THE 'in ( area_name) ' OPTION 

D ALLOCATED IN THE 'area' SPECIFIED (ONLY 'based' VARIABLES MAY 
BE ALLOCATED IN AN 'area') 

fl OMITTING THIS OPTION 

I ALLOCATED IN USER FREE AREA WITHIN [ pd] >[ uni que] . area .1 inker 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
THE 'allocate' AND 'free' STATEMENTS • 

• THE 'allocate' AND 'free' STATEMENTS HAVE THE FOLLOWING FORM WHEN 
USED FOR 'based' VARIABLES: 

i allocate ^id I set( locref ) ] [in( arearef ) 3 ; 
I WHERE 

I id IS THE NAME OF THE 'based' VARIABLE 

0 set( locref) IS USED TO DESIGNATE THE LOCATOR VARIABLE locref 
AS THE "ADDRESS" OF THE BEGINNING OF STORAGE GENERATED FOR 
THE 'based' VARIABLE id; 

0 MAY BE OMITTED IF THE VARIABLE id WAS DECLARED WITH THE 
♦ based ( Locref) ' ATTRIBUTE 

2 locref MUST SPECIFY A pointer OR offset 

Q in( arearef ) SPECIFIES THE • area' IN WHICH id IS TO BE ALLOCATED 

fl MAY BE OMITTED 

II free id [ in( arearef ) 3 ; 
fl WHERE 

1 id IS THE 'based' VARIABLE TO BE FREED AND MIGHT HAVE TO 
BE PTR QUALIFIED 

II in( arearef ) IS USED IF THE VARIABLE id WAS ALLOCATED IN 
THE 'area' arearef (AND IS OTHERWISE OMITTED) 

Q NOTE: POINTER IS NULLED AFTER 'based* VARIABLE IS FREED 
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EXPLICITLY ALLOCATED 'based' VARIABLES 



.THE 'allocate' AND 'free' STATEMENTS 



EXAMPLE 



P1: proc; 

del a(5,2) fixed based; 
del c char(40) based(pl); 

del AREA area; /* INTERNAL AUTOMATIC, BY DEFAULT */ 
del (p1,p2) pointer; 
del sysprint file; 

allocate a set(p2); 
p2 -> a = 0; 
allocate c in(AREA); 
c = "abedefg"; 



put skip(2) data(p2 -> a); 
free p2 -> a, c in(AREA); 
end P1 ; 
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EXPLICITLY ALLOCATED ' based* VARIABLES 
'area' DATA TYPES 

• THE PL/I DATA TYPE 'area 1 PROVIDES A POWERFUL FACILITY FOR STORAGE 
MANAGEMENT 

• BENEFITS OF 'area* MANAGEMENT 

II OPTIONS LIKE ZERO_ON_FREEING, ZERO ON_ALLOCATING , AND 
EXTENSIBILITY 

II ENABLES THE USE OF PL/1 OFFSETS 

I EASY FREEING WITH 'empty' BUILTIN 

• AN 'area' VARIABLE IS USED BY THE PROGRAMMER AS A MANAGED "POOL" OF 
FREE STORAGE, TO HOLD 'based' VARIABLES 

• THE MAXIMUM SIZE OF A NON-EXTENSIBLE 'area' IS 256K WORDS 

II THE CAPACITY IS ALWAYS SOMEWHAT LESS THAN THIS 

I THE "OCCUPATION RECORD" WHICH RESIDES AT THE BEGINNING OF AN 
'area' CATALOGS THE USAGE OF SPACE IN THE 'area' 

0 "ALLOCATION RECORDS" PRECEDE EACH BLOCK OF ALLOCATED STORAGE 
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EXPLICITLY ALLOCATED 'based* VARIABLES 
CREATING PL/I AREAS 

• AN 'area' MAY BE CREATED IN THREE WAYS: 

1 BY THE 'declare' STATEMENT (del A area( area size);) 

v/ v/vW«vVvl 

fl area size SPECIFIES THE NUMBER OF WORDS TO BE ALLOCATED FOR 
THE T area' VARIABLE 'A' (THE DEFAULT IS 1024 WORDS) 

fl THE LOCATION OF THE 'area' IS DETERMINED IN THE NORMAL FASHION, 
BY THE EVALUATION OF THE STORAGE CLASS ATTRIBUTE 

0 POSSIBLE ATTRIBUTES ARE static, automatic, internal, 
external, controlled AND based 

Q del A area; 

/* automatic - 'A' WOULD BE ALLOCATED ON THE STACK */ 

0 del B area based ( get_system_ free_ area_ ( ) ) ; 
del get_system_free_area_ entry returns (ptr); 

/* 'B' WOULD BE ALLOCATED IN "SYSTEM FREE STORAGE" */ 

0 BY THE «define_area_' SUBROUTINE 

S THE CALLER SPECIFIES THE LOCATION OF THE 'area 1 BY SUPPLYING 
A POINTER TO A SEGMENT IN WHICH THE 'area' IS TO BE ALLOCATED 

fl call define__ area_ (info_ptr, code); 

II IF A NULL POINTER IS SUPPLIED, THE SYSTEM ACQUIRES A SEGMENT 
FOR THE 'area' FROM THE PROCESS DIRECTORY TEMP SEG POOL 



fl MUST BE USED IF A BASED AREA IS OVERLAYED UPON ARBITRARY 
STORAGE 
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EXPLICITLY ALLOCATED 'baaed' VARIABLES 
CREATING PL/I AREAS 

Q BY THE 'create_area» COMMAND (AG92) 

D THE COMMAND-LEVEL INTERFACE TO ' def ine_area_' 

Q AT COMMAND-LEVEL: create^ area area_seg -extensible 
IN PROGRAM: del area__ seg$ external area; 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 

• LOCATORS SPECIFY THE "ADDRESS" OF AN OBJECT, AND ARE USED TO QUALIFY 
'based' VARIABLE REFERENCES 



• TWO TYPES OF 'locator' VARIABLES: 
D 'pointer' 

0 CONTAINS THE ABSOLUTE ADDRESS OF A BIT IN THE VIRTUAL MEMORY 

1 MAY BE ALIGNED OR UNALIGNED 

1 AN ALIGNED POINTER (DEFAULT) 

0 IS DOUBLE WORD ALIGNED 

1 IS A PAIR OF WORDS CONTAINING: 
15-BIT SEGMENT NUMBER 

3-BIT RING NUMBER 

6-BIT TAG FIELD CONTAINING OCTAL 43 

18-BIT WORD OFFSET 

6-BIT BIT OFFSET 

H IS DECLARED 

del my_pointer pointer; 

I IS SOMETIMES REFERRED TO AS AN ITS (INDIRECT TO SEGMENT) 
PAIR 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 

0 AN UNALIGNED POINTER 
II IS BIT ALIGNED 
I IS A SINGLE WORD CONTAINING 

6-BIT BIT OFFSET 

12-BIT SEGMENT NUMBER 

18-BIT WORD OFFSET 
I IS DECLARED 

del my_po inter unal ptr; 
I IS SOMETIMES REFERRED TO AS A PACKED POINTER 
I IS HANDLED BY SPECIAL HARDWARE INSTRUCTIONS 

II SINCE ONE OF THE COMPONENTS OF A 'pointer' IS THE SEGMENT 
NUMBER, THE 'pointer' VALUE IS INVALID ACROSS PROCESS BOUNDARIES 
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EXPLICITLY ALLOCATED 'based 1 VARIABLES 
LOCATOR DATA TYPES 

Q 'offset* 

0 AN ADDRESS TO A BIT IN AN 'area', RELATIVE TO THE BASE OF 
THAT 'area' 

0 COMPOSED OF A 18 BIT WORD OFFSET AND A 6-BIT BIT OFFSET 

1 AN 'offset' DECLARATION MUST BE QUALIFIED BY THE NAME OF THE 
'area' INTO WHICH THE 'oTFset' REFERS IF IT IS TO BE USED IN 
A 'based' VARIABLE REFERENCE 

II AN 'offset' IS VALID ACROSS PROCESS BOUNDARIES, SINCE IT DOES 
NOT REFER! TO A SEGMENT NUMBER 

I THE PL/I 'offset' ATTRIBUTE IS USED TO DECLARE AN 'offset' 
VARIABLE 

I del off 1 offset; 

S del off2 offset(A); WHERE 'A' HAS BEEN DECLARED AN 'area' 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
LOCATOR DATA TYPES 

• EXAMPLE USING POINTERS AND OFFSETS 



based_prog: proc; 

del sysprint file; 

del A area; /* DEFAULT SIZE IS 1024 WORDS */ 

del x fixed bin based; 

del c char (8) based; 

del p ptr; 

del o offset(A); 

allocate x set ( o) in (A); 
o -> x = 15; 
allocate c set ( p) ; 
p -> c = w abcdefgh w ; 
put skip data (o -> x, p -> c); 
free o -> x in (A); 
free p -> c; 
end based_ progj 



0 RESULT OF RUNNING ABOVE EXAMPLE 
! based_prog 

x= 15 c= h abcdefgh" ; 
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EXPLICITLY ALLOCATED ' based* VARIABLES 
LOCATOR ; builtin' FUNCTIONS 

• PL/I BUILTIN FUNCTIONS (AM83) ARE PROVIDED TO CONVERT BETWEEN 'pointer' 
AND 'offset 1 LOCATOR DATA TYPES: 

fl THE 'pointer' BUILTIN FUNCTION 

I CONVERTS AN 'offset' IN AN 'area' INTO A 'pointer' 

D pointer(X,A) 
ptr(X,A) 

0 RETURNS A POINTER POINTING TO 'offset' 'X' IN 'area' * A * 

Q THE 'offset' BUILTIN FUNCTION 

I CONVERTS A 'pointer' WHICH POINTS TO A LOCATION IN AN 'area' 
INTO THE 'offset' OF THAT LOCATION IN THE 'area' 

Q offset(P,A) 

0 RETURNS AN 'offset' TO THE 'based' VARIABLE LOCATED BY 
'pointer' 'P' IN 'area' 'A' 
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EXPLICITLY ALLOCATED 'based' VARIABLES 



LOCATOR 'builtin' FUNCTIONS 



• ADDITIONAL BUILTIN FUNCTIONS FOR THE MANIPULATION OF 'locator' AND 
'area' VARIABLES: 



H THE 'null' BUILTIN FUNCTION 



RETURNS THE VALUE OF THE NULL POINTER, THAT IS, A POINTER TO 
SEGMENT NUMBER -1 WITH WORD OFFSET 1 



1 IS USED TO TEST THE VALIDITY OF 'pointer' VALUES OR TO INITIALIZE 
THEM 



I NOTE THAT A 'pointer' VARIABLE CAN BE IN ONE OF THREE STATES: 

II UNDEFINED - NO VALUE HAS BEEN ASSIGNED, AND IF USED, 
' fault_tag_1 ' CONDITION IS USUALLY SIGNALLED 

1 NULL - THE 'null* BUILTIN HAS BEEN USED TO INITIALIZE THE 
'pointer' - AN ATTEMPT TO USE SUCH A 'pointer' USUALLY 
RESULTS IN THE SIGNALLING OF THE • null_pointer ' CONDITION 

1 NON-NULL - A LEGITIMATE ADDRESS HAS BEEN ASSIGNED 



2 THE 'nullo' BUILTIN FUNCTION 



H IS USED TO TEST THE VALIDITY OF 'offset' VALUES AND TO INITIALIZE 
THEM 



H A NULL OFFSET IS ALL "ONES" 
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EXPLICITLY ALLOCATED •based 1 VARIABLES 



LOCATOR 'builtin' FUNCTIONS 

0 THE »jddr' BUILTIN FUNCTION 

I RETURNS THE ADDRESS* OF ITS ARGUMENT AS A 'pointer 1 VALUE 

0 addr(x) RETURNS A 'pointer' WHICH LOCATES THE GENERATION OF 
STORAGE FOR 'x' 

D THE ^empty ' BUILTIN FUNCTION 

0 RETURNS THE "EMPTY" OR "NULL" VALUE OF DATA TYPE 'area' 

0 IS USED TO DETERMINE IF AN 'area' IS EMPTY AND IS ALSO USED 
TO INITIALIZE AN 'area' 

0 A "QUICK AND DIRTY" FREEING MECHANISM 

1 THE NONSTANDARD 'pointer' BUfLTIN FUNCTION 

1 RETURNS A 'pointer' VALUE GIVEN A 'pointer' POINTING ANYWHERE 
IN A SEGMENT AND A WORD OFFSET EXPRESSED AS AN ARITHMETIC OR 
BIT STRING VALUE 

0 pointer(P,N) OR ptr(P,N) RETURNS A 'pointer' TO THE Nth WORD 
OF THE SEGMENT 

1 IS DISTINGUISHED FROM THE STANDARD 'pointer' BUILTIN FUNCTION 
BY THE DATA TYPE OF THE ARGUMENTS 
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EXPLICITLY ALLOCATED 'based* VARIABLES 



LOCATOR 'builtin' FUNCTIONS 



0 THE NONSTANDARD 'addrel' BUILTIN FUNCTION 

II RETURNS A 'pointer' TO A WORD RELATIVE TO ANOTHER POINTER 

II addrel (P,N) POINTS TO A WORD N WORDS AWAY FROM P 

tt THE RESULTING POINTER HAS A 0 BIT OFFSET, REGARDLESS OF 
P'S BIT OFFSET 

I N IS AS IN THE ABOVE NONSTANDARD pointer BUILTIN 
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EXPLICITLY ALLOCATED 'based' VARIABLES 
USING EXPLICITLY ALLOCATED ' based* STORAGE 

• EXPLICITLY ALLOCATED 1 based 1 STORAGE IS GENERALLY USED FOR ONE OF 
THREE PURPOSES: 

I TO DIRECTLY CONTROL THE ALLOCATION AND FREEING OF STORAGE 

1 TO PROVIDE STORAGE FOR DATA ITEMS WHOSE EXTENTS ARE NOT KNOWN AT 
COMPILE TIME 

I TO TAKE ADVANTAGE OF CERTAIN FEATURES MADE AVAILABLE THROUGH THE 
USE OF 'area' VARIABLES 

I ZERO ON ALLOCATION 

0 ZERO ON FREEING 

1 MASS FREEING OF ALLOCATED VARIABLES 
II EXTENSIBILITY OF AREAS 
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EXPLICITLY ALLOCATED 'based 1 VARIABLES 



USING EXPLICITLY ALLOCATED 'based 1 STORAGE 



• EXPLICITLY ALLOCATED 'based* VARIABLES CAN BE USED TO PROVIDE STORAGE 
FOR DATA ITEMS WHOSE EXTENTS ARE NOT KNOWN AT COMPILE TIME 



II ADJUSTABLE EXTENTS ARE ARRAY BOUNDS, MAXIMUM STRING LENGTHS, AND 
'area' SIZES 



I UNLIKE 'controlled' VARIABLES, FOR 'based' VARIABLES, THE VALUES 
OF VARIABLE EXTENTS ARE COMPUTED FOR EACH REFERENCE 



0 THAT IS, THE ADJUSTED EXTENTS ARE NOT SAVED WHEN THE VARIABLE 
IS FIRST ALLOCATED 



I IT IS THE RESPONSIBILITY OF THE PROGRAM TO PRESERVE SUCH EXTENTS 
TO AVOID VIOLATING THE PL/I CONSISTENCY RULES 
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EXPLICITLY ALLOCATED ' based* VARIABLES 



USING EXPLICITLY ALLOCATED 1 based' STORAGE 



Q EXAMPLE OF AN INVALID PROGRAM 



P1: proc; 

» del n fixed bin; 

del S char(n+2) based(beta); 
del beta pointer; 

• • • 
n = 4; 
allocate S; 

• • • 
"7n = 100; 

S = "abedef"; 

• • • 
free S; 

end; 



0 THIS PROGRAM IS INVALID 

I WHEN THE 'based' VARIABLE 'S' IS ALLOCATED, IT IS GIVEN 6 
BYTES OF STORAGE 

A WHEN IT IS REFERENCED IN THE ASSIGNMENT STATEMENT, THE 
EXTENTS ARE RECOMPUTED TO 102, AND THE STRING "abedef" 
WILL BE PADDED TO A LENGTH OF 102 BEFORE BEING ASSIGNED 
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EXPLICITLY ALLOCATED 'based' VARIABLES 



THE 'refer' OPTION 



• SINCE THE VARIABLE EXTENTS OF 'based' VARIABLES ARE NOT SAVED BY 
PL/I, A SPECIAL FEATURE, THE 'refer' OPTION IS PROVIDED 



II IT IS USED TO SAVE THE VALUE CALCULATED FOR VARIABLE EXTENTS OF 
A 'based' VARIABLE WHEN IT IS ALLOCATED 



I IT IS USED WITHIN A STRUCTURE VARIABLE TO CREATE A " SELF -DEFINING 
STRUCTURE" , WHICH CARRIES ITS OWN EXTENTS 
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EXPLICITLY ALLOCATED 'based' VARIABLES 



THE 'refer' OPTION 



fl A VALID EXAMPLE 



P3: 


proc; 


del 


n fixed bin; 


del 


1 Spair based(beta), 




2 n2 fixed bin , 




2 S char(n+2 refer(n2)); 


del 


beta ptr ; 




• • • 

n r 4; 




allocate Spair; 




n = 100; 




Spair. S = "abedef"; 




• • • 

free Spair; 


end 


P3; 



D MOTE: A PARENTHESIZED REFERENCE FOLLOWING THE KEYWORD 'refer' 
MUST DESIGNATE A SCALAR MEMBER DEFINED EARLIER IN THE SAME STRUCTURE 



1 AT ALLOCATION TIME, ANY INITIAL EXTENT EXPRESSION IS EVALUATED, 
AND IS SAVED IN THE MEMBER REFERENCED BY THE 'refer' OPTION 
CLAUSE 



I ON SUBSEQUENT REFERENCES TO THE 'based' ADJUSTABLE VARIABLE, THE 
EXTENT IS DETERMINED BY REFERRING TO THE MEMBER 
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EXPLICITLY ALLOCATED 1 based 1 VARIABLES 



USING 'area' VARIABLES 



• EXPLICITLY ALLOCATED 'based' VARIABLES MAY BE USED TO TAKE ADVANTAGE 
OF THE STORAGE MANAGEMENT FACILITIES OFFERED BY THE- PL/I 'area' 
VARIABLES 



• NOTE THAT THE ONLY TYPE OF VARIABLE WHICH MAY BE ALLOCATED IN AN 
'area' IS AN EXPLICITLY ALLOCATED 'based' VARIABLE 



• NOTE ALSO THAT PL/1 'offset' VALUES CAN ONLY LOCATE STORAGE WITHIN 
AREAS 
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EQUIVALENCED 'based' STORAGE 



• THE USE OF EQUIVALENCED 'based' VARIABLES IS ONE OF THE MOST POWERFUL 
STORAGE MANAGEMENT CAPABILITIES OFFERED BY PL/I 



• UNLIKE EXPLICITLY ALLOCATED 'based' VARIABLES, AN EQUIVALENCED 'based 1 
VARIABLE: 



II IS SUPERIMPOSED ON OR EQUIVALENCED TO A PREVIOUSLY ALLOCATED 
"BASE" VARIABLE 



H NEVER HAS STORAGE OF ITS OWN, AND THUS IS NEVER ALLOCATED OR 
FREED 



• THE LOCATOR VALUE USED TO REFERENCE THE BASE VARIABLE IS OBTAINED 
BY THE »addr« BUILTIN FUNCTION 



• EXAMPLE 



del 


a fixed bin (35); 


del 


b fixed bin (35) based (addr(a)); 




a = 5; 




b = 2; 




put skip list ( a ,b) ; 
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EQUIVALENCED 'based' STORAGE 



• ADDITIONAL EXAMPLES (NOTE: FOR THESE EXAMPLES, THE DATA TYPE OF 
THE 'based' VARIABLE IS THE SAME AS THAT OF THE BASE VARIABLE) 



Q EXAMPLE 1 



P1 : 


proc; 


del 


x fixed dec(5,2); 


del 


y fixed dec(5,2) based; 


del 


p ptr; 


del 


( sysin ,sysprint) file; 




p = addr( x) ; 




get list( x) ; 




put skip list(2 * p->y); 


end 


P1; 



Q EXAMPLE 2 







del 


1 A(5), 




2 x fixed bin, 




2 y ehar(6); 


del 


1 B based , 




2 r fixed bin, 




2 s char(6); 


del 


P Ptr; 




p = addr(A(3)); 




p -> B.s = "third"; 


/* 


SETS A(3).y TO "third" */ 
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EQUIVALENCED 'based' STORAGE 



• IT IS ALSO POSSIBLE FOR THE DATA TYPES OF THE 'based' AND BASE 
VARIABLE TO DIFFER 



I EXAMPLE 1 



del x fixed bin(35); 

del y bit(36) based (addr(x)); 

x = 5; 

put skip list ( x ,y) ; 



II EXAMPLE 2 



del number(1024) float bin; 
del 1 f loatjium based , 

2 sign bit( 1 ) unal , 
2 exponent bit(7) unal, 
2 m_ sign bit( 1 ) unal, 
2 mantissa bit(27) unal; 
• • • 

p = addr( number ( 43 ) ) ; 



p -> float_num MEANS number (43) 

p -> sign MEANS bit 0 of number(43) 

p -> mantissa MEANS bits 9-35 of number(43) 



8 
D 
D 
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EQUIVALENCED 1 based* STORAGE 



del x char<8) varying init(" ABC" ) ; 

del 1 y based (addr(x)), 

2 length fixed bin (35), 
2 actuai_string char (8); 



X I 3 


A 


B 


C 


/ 


/ 


A 




/ 


length j 




actual _string 





x = "BOIMJOUR"; 
if y.iength = 7 

then put list (y.actual_string) ; 
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AN APPLICATION FOR 'based* VARIABLES 
LINKED INFORMATION STRUCTURES 

• EQUIVALENCED 'based' STRUCTURES CAN BE USED TO PROVIDE STORAGE FOR 
DATA ITEMS WHICH HAVE BEEN ORGANIZED INTO AN ARBITRARILY LINKED 
INFORMATION NETWORK 

1 SINGLY AND DOUBLY LINKED LISTS 
5 TERMINATING LISTS 
I CIRCULAR LISTS 

D TREES AND OTHER DIRECTED GRAPHS 

H OTHER INFORMATION NETWORKS 



• IT SHOULD BE NOTED THAT SUCH STRUCTURES ARE HEAVILY USED IN THE 
SUPERVISOR, AND THAT MOST OF THE SUPERVISOR DATABASES ARE 'based' 
STRUCTURES DEFINED IN "INCLUDE FILES" SUBORDINATE TO >ldd> include 



Not To Be Reproduced 



3-2 8 



F15C 



AN APPLICATION FOR 1 based 1 VARIABLES 



LINKED INFORMATION STRUCTURES 



* AN EXAMPLE (from stack frame .incl .p!1 ) 



del 1 stack_frame based(sp) aligned, 

2 po in ter_ register s(0 : 7) ptr, 

2 pr ev_sp""po inter , /* points to previous stack frame */ 

2 next^sp pointer, /* points to next stack frame */ 

2 return_ptr pointer, 

2 entry_ptr pointer, 

2 operator_and_lp_ ptr ptr , 

2 arg_ptr pointer, 

2 static^ ptr ptr unaligned, 

2 support_ptr ptr unaligned, 

2 on_ unit_rel p1 bit(l8) unaligned, 

2 on_unit_relp2 bit(18) unaligned, 

2 t ran si a to r_ id bit(l8) unaligned, 

2 operator_return_of f set bit(18) unaligned, 

2 x(0: 7) bit(l8) unaligned, 

2 a bit(36) , 

2 q bit(36) , 

2 e bit(36) , 

2 timer bit(27) unaligned, 

2 pad bit(6) unaligned, 

2 ring_alarm_reg bit(3) unaligned; 



• THERE ARE OVER 2000 SUCH INCLUDE FILES IN >ldd> include (TOPIC 5 
DEMONSTRATES THEIR USAGE) 



YOU ARE NOW READY FOR WORKSHOP 
#2 
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Topic IV INTRODUCTION TO MULTICS SUBROUTINES Topic IV 

OBJECTIVES: 

Upon completion of this topic* students should be able to! 

1. Give reasons for having a set of Multics subroutines. 

2. Give general guidelines for use of Multics system 
subroutines . 

3. List some of the conventions followed when using Multics 
system subroutines. 



Multics 
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WHAT ARE SYSTEM SUBROUTINES? 



• SYSTEM SUBROUTINES ARE CALLABLE PROCEDURES USED BY THE MULTICS 
OPERATING SYSTEM 



I THEY ARE THE SUBROUTINES THAT THE PROGRAMMER USES TO PERFORM 
COMMAND LEVEL LIKE FUNCTIONS 



I THEY ARE THE PROCEDURES ACTUALLY CALLED BY COMMAND PROCEDURES 
(EXAMPLE: THE delete COMMAND PROCEDURE CALLS THE delete 
SUBROUTINE) 

0 SOME SUBROUTINES HAVE A ONE-TO-ONE RELATION WITH MULTICS COMMANDS 
(EXAMPLE: send_message_ SUBROUTINE PERFORMS THE send_message 
COMMAND FUNCTION FROM WITHIN A PROGRAM) 



0 OTHER SUBROUTINES PERFORM ONLY A SMALL PART OF WHAT AN ENTIRE 
COMMAND DOES. EXAMPLES: 

D iox_ SUBROUTINES ARE USED BY SEVERAL COMMANDS 

1 convert_date_to_binary_ IS JUST ONE OF MANY SUBROUTINES 
CALLED BY THE en ter_abs_re quest AND memo COMMANDS- 
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SYSTEM SUBROUTINE CONVENTIONS 



• SYSTEM SUBROUTINE ENTRY NAMES END IN AN UNDERSCORE ( ) 



• MANY SUBROUTINES HAVE SEVERAL ENTRY POINTS 

B hcs_ $list_acl 
hcs_ $make_seg 
hcs $ status 



• THEY ARE DOCUMENTED IN MULTICS SUBROUTINES & I/O MODULES (AG93) 



# THEY ARE LOCATED PRIMARILY IN >system library standard AND 
> sy s t em_ 1 ib r ar y 1 



• THEY ARE WRITTEN IN PL/I OR ALM 
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USING SYSTEM SUBROUTINES 



• SINCE THEY ARE EXTERNAL SUBROUTINES, EACH MUST BE DECLARED IN THE 
USER'S PROGRAM AS 'external entry' 



0 THE DATA TYPES FOR THE PARAMETER LIST CAN BE FOUND IN THE MANUAL 
DESCRIPTION OF THE SUBROUTINE 



II IF THEY ACCEPT A VARIABLE NUMBER OF ARGUMENTS, THEY ARE DECLARED 
'entry options (variable)' 



# SEVERAL MAKE USE OF STRUCTURES TO PASS DATA TO AND FROM THE CALLING 
PROCEDURE 



I IN THIS CASE, ONE OF THE ARGUMENTS PASSED TO THE PROCEDURE IS A 
POINTER TO THAT STRUCTURE 



I THE DECLARATIONS REQUIRED FOR THESE STRUCTURES ARE FOUND IN THE 
DOCUMENTATION FOR THE SUBROUTINE 



1 THE DECLARATIONS OF SOME OF THESE STRUCTURES ARE FOUND IN INCLUDE 
FILES IN >ldd> include 



Q EXAMPLE: hcs_$status_ 

0 THIS SUBROUTINE IS PASSED A- POINTER TO A STRUCTURE INTO WHICH 
IT IS TO PUT ITS INFORMATION 

1 A DECLARATION FOR THAT STRUCTURE IS FOUND IN 
> ldd>include> status structures. incl.pH (FURTHER DISCUSSED IN 
TOPIC 10) 
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STATUS CODES 



• ONE OF THE OUTPUT ARGUMENTS OF A SUBROUTINE IS USUALLY A ■ status 
code' 



0 THE 'status code' IS THE MEANS BY WHICH THE CALLED PROCEDURE MAY 
REPORT ANY UNUSUAL OCCURRENCE TO ITS IMMEDIATE CALLER 



3 THE VARIABLE THAT RECEIVES THE 'status code 1 MUST BE DECLARED 
•fixed bin(35) f 



Q IF THE SUBROUTINE RUNS TO COMPLETION WITH ABSOLUTELY NO ABNORMAL 
CONDITIONS TO REPORT, THE STATUS CODE IS 0 (ZERO) 



• com err 



D USED TO REPORT ERRORS FROM WITHIN A PROGRAM 



I TYPICAL USAGE 



del com_err entry options (variable); 
del code fixed bin(35); 

• • • 

call hes $status -> " ( ,code) ; 

if code *s 0 
then do;. 

call eom_err_ ( code , - gamma"); 
return; 

end; 



I IF AN ERROR OCCURRED, IT MIGHT PRINT SOMETHING LIKE: 
gamma: Incorrect access to directory containing... 



D SOME NON-ZERO STATUS CODES DO NOT INDICATE AN ERROR 
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STATUS CODES 



Q STATUS CODES AND THEIR MEANINGS ARE LISTED IN CHAPTER 7 OF THE 
MULTICS PROGRAMMER'S REFERENCE GUIDE (AG91 ) 



0 THE STANDARD STATUS CODES AND THEIR CORRESPONDING MESSAGES ARE 
IN A SEGMENT CALLED error_table_ , WHICH IS IN >s!1 



I IT IS POSSIBLE TO TEST FOR A PARTICULAR STATUS CODE VALUE USING 
THE SYMBOLIC REPRESENTATION 

del error — tab le_$ seg known external fixed bin(35); 
• • • 

if code = error_tab!e_$ seg known 
then do; 

call com_err (code, "beta"); 
goto try_agaTn; 

end; 
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STATUS CODES 



0 THE probe 'display' REQUEST CAN BE USED TO DISPLAY THE ERROR 
MESSAGE ASSOCIATED WITH A STATUS CODE 



seg known : proc; 



del 


initiate^ file_ 


entry (char(*), char( 


*) , bit(») , ptr, 
fixed bin(35)); 






fixed bin(24) , 


del 


seg_ ptr 


pointer ; 


del 


bit" count 


fixed bin (24); 




del 


code 


fixed bin (35); 




del 


null 


builtin; 





call initiate_file_ ( ">udd>MED> jcj>15c" , "foo", "101 "b, seg_ptr , 

bit_count, code); 

end /* seg known */; 



r 11:41 0. 100 3 
! seg known 

Stopped after line 10 of segknown. (level 5) 
! sc 

call initiate_file_ ( ">udd>MED> jcj>15c" , "foo", "101"b, seg_ptr 
~" bit — count, code); 

! v seg_ ptr 

seg_ptr = null 
! v code 

code = 8589679427 
! display code code 

error_table_$ noentry "Entry not found." 
! q 

r 11:42 0.733 86 

! Is foo 

list: foo not found 
r 11:42 0.212 11 
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Topic V ADVANCED BASED VARIABLE USAGE Topic V 

OBJECTIVES: 

Upon completion of this topic? students should be able to: 

1. Use Multics subroutines to manipulate segments directly 
instead of usins PL/1 I/O statements. 

2. Manipulate archive components usins Multics subroutines. 

3. Exami ne some system databases usins based structures and 
Multics subroutines. 



Multics 
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GAINING DIRECT ACCESS TO SEGMENTS 



MOTIVATION 



# EQUIVALENCED BASED VARIABLES CAN BE USED TO GAIN DIRECT ACCESS TO 
SEGMENTS IN THE VIRTUAL MEMORY 



I IN THIS WAY, AN ENTIRE DATA SEGMENT CAN BE ACCESSED WITHOUT 
RESORTING TO LANGUAGE I/O 



I ONE MUST OBTAIN A 'pointer* TO THE SEGMENT IN ORDER TO GAIN 
DIRECT ACCESS TO IT 



1 THE FOLLOWING PAGES SHOW SUBROUTINES THAT RETURN A POINTER TO A 
SEGMENT 
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GAINING DIRECT ACCESS TO SEGMENTS 



OBTAINING A POINTER TO A SEGMENT 



• MULTICS SUBROUTINES WHICH OBTAIN A 'pointer' TO A SEGMENT: 

fl hcs — $make — seg 

D BASIC FUNCTIONS 

I SEGMENT CREATION IF IT DOES NOT EXIST 
I SEGMENT INITIATION 

II USAGE 

del hes $make seg entry 



(char(») , 
char( *) , 
char ( *) , 



/* INPUT */ 
/* INPUT */ 
/* INPUT */ 
/* INPUT */ 
/* OUTPUT */ 
/* OUTPUT */ 



fixed bin(5), 
ptr , 

fixed bin(35)); 



call hes $make seg 



( dir — name , 
ent7yname , 
ref_name , 
mode , 
seg_ptr , 
code) ; 



/* PATH OF CONTAINING DIR*/ 

/* SEGMENT NAME »/ u 

/* DESIRED REFERENCE NAME */ = 

/* ACCESS FOR THIS USER */ 

/* POINTS TO CREATED/FOUND SEG */ 

/* STATUS CODE */ 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 

0 NOTES 

1 IF SEGMENT DOESN'T EXIST, APPEND PERMISSION REQUIRED ON 
CONTAINING DIRECTORY 

H MAKING-KNOWN REQUIRES NONNULL ACCESS ON SEGMENT 

I IF entryname IS NULL, UNIQUE SEGNAME IS GENERATED 

II IF dir_name IS NULL, SEGMENT IS CREATED IN PROCESS DIRECTORY 
I ref_name USUALLY NULL 

I mode ENCODES THUSLY 

READ -> 01000b 
EXECUTE -> 00100b 
WRITE -> 00010b 

0 seg_ptr IS RETURNED NULL IF REAL TROUBLE WAS ENCOUNTERED 

B code MIGHT BE NON-ZERO UNDER 'NORMAL' CIRCUMSTANCES: 

error_ table_$ named up 
error table $segknown 
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GAINING DIRECT ACCESS TO SEGMENTS 



OBTAINING A POINTER TO A SEGMENT 



Q IF THE PROGRAMMER DOESN'T CARE IF THE SEGMENT ALREADY EXISTS 
OR IS ALREADY INITIATED HE RELIES ONLY ON THE NON-NULL seg_ptr 



del hcs_$make_seg entry (char (*) , char (*), char (*), 

fixed bin (5), ptr , fixed bin (35)); 
del com_err_ entry options (variable); 



call hcs_$make_ seg( seg_ptr , code); 

if seg — ptr = nullO 
then do; 

call cora_err_ (code, "alpha"); 
• • • 

end; 



Q IF THE PROGRAMMER EXPECTS" TO BE CREATING A NEW SEGMENT AND 
DOES NOT WANT TO REFERENCE AN ALREADY EXISTING SEGMENT, HE 
MUST CHECK THE CODE' 



del hcs_$make_seg entry (char (*), char (*), char (*), 

fixed bin (5), ptr, fixed bin (35)); 
del com — err_ entry options (variable); 
del error_table_$ named up fixed bin(35) ext static; 
del error_table_$seg known fixed bin(35) ext statie; 



• 

call hes $make — seg ( seg_ptr , code); 

if seg_ p€r = riullO S code = error_ tabie_$ seg known 

I code = error_table~$ named up 

then do ; 

call com — err_ (code, "alpha"); 
• • • 

end; 
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GAINING DIRECT ACCESS TO SEGMENTS 
OBTAINING A POINTER TO A SEGMENT 



Q initiate file 



Q BASIC FUNCTIONS 

I MAKES A SEGMENT KNOWN WITH A NULL REFERENCE NAME 

I CHECKS THAT THE USER'S PROCESS HAS AT LEAST THE DESIRED 
ACCESS ON THE SEGMENT 

I RETURNS A POINTER TO THE SEGMENT 

I RETURNS A BIT COUNT 



I USAGE 

del initiate file entry 
(char(*), 
char(*) , 
bit(*) , 
pointer , 

fixed binary (24) , 
fixed binary (35)) ; 

call initiate^ file 
(dirnameT 
entr ynarae , 
mod e , 
seg_ptr , 
bit_count , 
code) ; 



/* INPUT */ 
/* INPUT */ 
/* INPUT */ 
/* OUTPUT */ 
/* OUTPUT */ 
/* OUTPUT */ 



/* PATH OF 'CONTAINING DIR */ 
/* SEGMENT NAME */ 
/* REQUIRED ACCESS MODE •/ 
/* POINTS TO INITIATED SEG */ 
/* BIT COUNT OF SEGMENT */ 
/♦ STANDARD SYSTEM CODE */ 
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GAINING DIRECT ACCESS TO SEGMENTS 



OBTAINING A POINTER TO A SEGMENT 



0 NOTES 

I THE SEGMENT MUST EXIST 

I MAKING-KNOWN REQUIRES NONNULL ACCESS ON THE SEGMENT, AS 
WELL AS THE REQUIRED MODES SPECIFIED IN THE CALL 

I mode ENCODES THUSLY ' 

READ -> "100"b 
EXECUTE -> "010"b 
WRITE -> "001 "b 

(>ldd>include> access mode_values.incl.pl1 CONTAINS NAMED 
CONSTANTS FOR THESE ACCESS MODES) 

0 seg_ptr IS NULL IF THE SEGMENT IS NOT MADE KNOWN 

1 code IS A STANDARD STATUS CODE AND COULD BE: 

error_table_$no_r_ permission 
er r o r_ t a b 1 e_ $ no_ e_ pe r m i s s i o n 
error~table $no w~"permission 
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GAINING DIRECT ACCESS TO SEGMENTS 



OBTAINING A POINTER TO A SEGMENT 



0 initiate_file_$ component 



D BASIC FUNCTIONS 

1 MAKES EITHER A SEGMENT OR AN ARCHIVE COMPONENT KNOWN WITH 
A NULL REFERENCE NAME 

I IF NO COMPONENT NAME IS SPECIFIED, THIS ENTRY POINT IS 
IDENTICAL TO initiate file 



0 USAGE 

del initiate file_$ component entry 

(char (*T, /* INPUT */ 

char (*) , /* INPUT */ 

char (*) , /* INPUT */ 

bit (*) , /* INPUT */ 

pointer, /* OUTPUT */ 

fixed binary (24), /* OUTPUT */ 

fixed binary (35)); /* OUTPUT */ 

call initiate^ file_$ component 

(dirname, ~ /* PATH OF CONTAINING DIR *L 

entryname, /* NAME OF SEGMENT OR ARCHIVE */ 

com pc n en t_ name, /* NULL OR NAME OF COMPONENT */ 

mode, ~ /* REQUIRED ACCESS MODE */ 

component ptr , /* PTR TO SEGMENT OR COMPONENT */ 

bit count, /* BIT COUNT OF SEGMENT OR COMPONENT */ 

code) ; /* STANDARD SYSTEM CODE */ 



0 NOTES 

I THE ARCHIVE COMPONENT MAY NOT BE MODIFIED (ONLY READ ACCESS 
IS PERMITTED) 

Q ONLY THE DATA STARTING AT THE POINTER AND EXTENDING AS FAR 
AS THE BIT COUNT MAY BE REFERENCED (NO DATA BEFORE OR 
AFTER THE COMPONENT MAY BE REFERENCED) 
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GAINING DIRECT ACCESS TO SEGMENTS 



OBTAINING A POINTER TO A SEGMENT 

0 TO OBTAIN A POINTER TO A COMPONENT WITHIN AN ARCHIVE SEGMENT SEE 
E archive^ $get_ component 
Q archive $next component 



• NOTE THAT THE SUBROUTINES DISCUSSED REQUIRE AN ABSOLUTE DIRECTORY 
PATHNAME 



• THE expand pathname SUBROUTINE CAN BE USED TO CONVERT A PATHNAME 
(WHETHER RELATIVE Off ABSOLUTE) INTO THE REQUIRED DIRECTORY PATHNAME 
AND ENTRYNAME STRINGS 



I USAGE 



del expand pathname entry 

(Char(*), charC) , char(»), fixed bin(35)); 

call ex pand_ pathname 

(rel_path, 7* RELATIVE OR ABSOLUTE PATHNAME 

TO BE EXPANDED */ 
dir_name, /* RETURNED DIRECTORY PORTION OF 

PATHNAME */ 

entryname , /* RETURNED ENTRYNAME PORTION OF 

PATHNAME */ 

code) ; 
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GAINING DIRECT ACCESS TO SEGMENTS 



AN EXAMPLE 



stack_tracer : proc; 

% include staek_header ; 
% include stack_frame; 

del com_ err_ entry options (variable); 

del get~~pdir_ entry () returns (char (168)); 

del initiate_file_ entry (char (*) , char (*) , bit (*), pointer, 

fixed binary (24), fixed binary (35)); 
del interpret_ptr_ entry ( ptr , ptr, ptr) ; 

del bit — count fixed binary (24); 

del code fixed bin (35); 

del ME char (12) static 

in it ( n stack_ tracer") options (constant); 

del no — frames fixed bin; 
del 1 owner , 

2 message char (64), 

2 segname char (32), 

2 entryname char (33); 
del ( save_ptr 

shp) ' ptr; 

del sysprint file; 
del (addr, 
ltrim , 

null) builtin; 



/* GET POINTER TO BASE OF STACK SEGMENT */ 

call initiate_file_ (get_pdir_ () , "stack 4", "100"b, 

shp, bit_count, codeT; 

if shp = null () 
then do; 

call com_ err_ (code, ME); 
return ; 
end /• then do */; 

/* WALK FRAMES TO FIND LAST ONE */ 

no_ frames = 0; 

do sp s shp -> stack_header .stack_begin_ptr 
repeat sp -> stack_fr ame .nex t sp 
while ( sp ~s shp -5 stack^heaH'er ,stack_end_ptr) ; 
save_ptr = sp; 
no frames = no_frames + 1; 
end / 7 do sp */; 

/* NOW TRACE BACKWARDS AND DUMP.*/ 
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GAINING DIRECT ACCESS TO SEGMENTS 



AN EXAMPLE 



do sp = save^ptr 

repeat sp -> stack frame. prev sp 
while ( sp * = null T) ) ; 
call inter pre t — ptr_ ( sp -> stack frame .en try_ptr , sp, 

~~ addr (ownerT); 
put skip (2) edit ("FRAME", no_frames, " IS OWNED BY ", 

rtrim( ownerTsegname) , rtrim( owner .entryname) ) 
(a f(3) s s a)* 
put skip list (" FRAME STARTS AT", sp) ; 

put skip list (" ARG POINTER IS", sp -> stack_fr ame .arg_ptr ) ; 
no frames = no_frames -1 ; 
end /*" do sp */; 

/* ALL DONE */ 

put skip (2) list ("End stack_ tracer" ) ; 
put skip; 

close file (sysprint); 
end /* stack_tracer */; 



r 14:08 0.237 6 
! stack tracer 



FRAME 5 IS OWNED BY stack tracerSst^ck t/acer 
FRAME STARTS AT pointer (2 34 15^40) 

ARG POINTER IS pointer (234 ! 5202 ) 

FRAME 4 IS OWNED BY command processor $command processor 
FRAME STARTS AT pointer (234 1^000) 

ARG POINTER IS pointer ( 234 ! 4274 ) 

FRAME 3 IS OWNED BY abbrev$ abbrev_cp 

FRAME STARTS AT pointer(234 12700 ) 

ARG POINTER IS pointer (234 !2564 ) 

FRAME 2 IS OWNED BY listen $listen_ 

FRAME STARTS AT pointer (234 12400 ) 

ARG POINTER IS pointer (234 12236 ) 

FRAME 1 IS 0WNED_BY initial ize_process_$ initial ize_process 
FRAMt STARTS At pointer (234 12000 ) 

ARG POINTER IS pointer (234 10 ) 

End stack tracer 
r 14:09 07658 46 
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GAINING DIRECT ACCESS TO SEGMENTS 
AN EXAMPLE 



YOU ARE NOW READY FOR WORKSHOP 
#3 

I! 
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Topic VI MULTICS CONDITION MECHANISM Topic VI 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1. Describe the actions taken by Multics when a condition is 
si snal led. 

2. Write handlers for the following conditions: 

c leanup 

pros ram- i nter rupt 
finish 

User-defined and PL/1-defined conditions 

3. Write an "any_other " handler. 

4. Discuss the circumstances under which the system-defined 
conditions occur. 



Multics 
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INTRODUCTION 

• THE MULT ICS CONDITION MECHANISM IS A FACILITY THAT NOTIFIES A PROGRAM 
OF AN EXCEPTIONAL CONDITION 

1 A CONDITION IS A STATE OF THE EXECUTING PROCESS 

I A CONDITION MAY OR MAY NOT INDICATE THAT AN ERROR HAS OCCURRED 

• IN MULTICS, THERE ARE THREE BROAD CATEGORIES OF CONDITIONS: 

1 SYSTEM-DEFINED CONDITIONS (MULTICS LEVEL) 
11 ARE DEFINED AS PART OF THE MULTICS SYSTEM 

1 ARE DETECTED BY THE MULTICS HARDWARE OR SOFTWARE 

2 ARE SIGNALLED BY THE MULTICS SUPERVISOR 

I EXAMPLES 

I cleanup 

Q no_ read_ permission 

Q out_ of_bound s 

0 quit 

Q r ec o r d__ quo ta_ over flow • 

0 AND OTHERS, TO BE DISCUSSED LATER 
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INTRODUCTION 

Q LANGUAGE -DEFINED CONDITIONS 
I ARE DEFINED AS PART OF PL/I 

I ARE DETECTED AND SIGNALLED BY THE PL/I RUNTIME PROCESSOR 

I EXAMPLES 

I conversion 

0 end file 

D AND OTHERS. . . 

D PROGRAMMER-DEFINED CONDITIONS 
I ARE DEFINED BY THE PROGRAMMER 

I ARE DETECTED AND SIGNALLED EXPLICITLY BY THE PROGRAMMER 

I EXAMPLES 

1 oops 

Q OR WHATEVER ONE DESIRES... 
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INTRODUCTION 



* THE MULT ICS CONDITION MECHANISM IS INVOKED WHEN A CONDITION IS DETECTED 
AND SIGNALLED BY: 

I THE SYSTEM 

I EXAMPLE: zerodivide OCCURS 

I THE USER PROGRAM 

i EXAMPLE: "signal zerodivide;" 
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INTRODUCTION 



• THE SIGNALLING OF A CONDITION: 



0 IMMEDIATELY STOPS THE PROGRAM AT THE CURRENT POINT OF EXECUTION 



II CAUSES A BLOCK ACTIVATION OF THE MOST RECENTLY ESTABLISHED ON 
UNIT FOR THAT CONDITION 



THE APPROPRIATE ON UNIT IS FOUND BY MAKING A BACKWARDS TRACE 
OF THE STACK 



EACH BLOCK ACTIVATION ON THE STACK CAN HAVE ONLY ONE ON UNIT 
ESTABLISHED FOR EACH CONDITION AT ANY GIVEN TIME 



sub2$sub2 



subl $sub1 



main$main 



command_processor_ 



ON UNIT ESTABLISHED FOR zerodivide 



ON UNIT ESTABLISHED FOR zerodivide 



abbrev 



listen 



initialize process 



USER STACK 
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INTRODUCTION 



Q IF zerodivide IS SIGNALLED IN sub2, A BLOCK IS ACTIVATED FOR THE 
ON UNIT ESTABLISHED IN subl 



subl $zerodivide .n 



( signal^) 



( pl1_signal_from_ops_) 



sub2$sub2 



subl $sub1 



main$main 



command_processor_ 



abbrev 



listen 



initial ize_proc ess_ 



ON UNIT ESTABLISHED FOR zerodivide 



ON UNIT ESTABLISHED FOR zerodivide 



USER STACK 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



jm. t?v it um c* <? nr rcru n t to utmp r« aittvtt tom u a mt\t r» n o 

1 on zerodivide begin; 

• • • 

• • • 
end; 

I on zerodivide system; 

I on zerodivide snap system; 

I IF THE CONDITION SPECIFIED IS SIGNALLED, THE 'probe' COMMAND 
IS IMMEDIATELY INVOKED BEFORE THE 1 on unit* IS INVOKED (FOR 
AN ABSENTEE PROCESS, THE ' tr ace_stack' COMMAND IS EXECUTED) 

Q on zerodivide call probe; 



• THERE ARE THREE WAYS TO REVERT AN 'on unit' 

C PL/I 'revert' STATEMENT (EXAMPLE: revert zerodivide;) 

0 BLOCK DEACTIVATION CAUSED BY REACHING A BLOCK 'end' STATEMENT 

1 NON-LOCAL 'go to' WHICH CAUSES DEACTIVATION OF OF ALL BLOCKS 
FROM THE TOP OF THE STACK TO THE PROCEDURE CONTAINING THE LABEL 
THAT IS THE TARGET OF THE 'go to' 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



This Page Intentionally Left Blank 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



* EXAMPLE OF THE CONDITION MECHANISM 



example: proc; 

del sub! external entry; 
del sub2 external entry ; 
del overflow condition; 

on overflow <on unit 1>; 

call subl; 

< statement 1>; 

call sub 2; 
end /* example »/; 



subl : proc; 

del overflow condition; 

< statement 2>; 

on overflow <on unit 2>; 

< statement 3>; 
end /* subl */; 



sub2: proc; 

del overflow condition; 

< statement 4>; 
on overflow <on unit 3>; 

< statement 5>; 

revert overflow; 

< statement 6>; 
end /* sub2 */; 
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ESTABLISHING AND REVERTING CONDITION HANDLERS 



• ASSUME THAT EACH OF THE 6 NUMBERED STATEMENTS IN THE 3 PROCEDURES 
ON THE PREVIOUS PAGE IS A SIMPLE ASSIGNMENT STATEMENT (THERE ARE NO 
goto 1 s) 

FILL IN THE CHART SHOWING WHICH *on unit* WOULD BE INVOKED IF 'overflow' 
OCCURRED IN THE NUMBERED STATEMENT SPECIFIED 

STATEMENT CAUSING overflow 

TO BE SIGNALLED ON UNIT INVOKED 

1 . 

2 

3 

4 

5 

6 
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A SPECIAL CATCH-ALL CONDITION HANDLER 



# THE • any. other f CONDITION REFERS TO CONDITIONS FOR WHICH NO 'on 
unit' HAS" BEEN SPECIFICALLY ESTABLISHED 

I EXAMPLE 

del (zerodivide, overflow, any_other) condition; 

on zerodivide begin; 

• • • 
end; 

on any_other begin; 

• • • 
end; 

signal overflow; 

1 BACKWARD TRACE OF STACK LOOKS FOR CONDITION HANDLER TWICE FOR 
EACH FRAME: 

H LOOKS FOR SPECIFIC CONDITION HANDLER FIRST 

1 LOOKS FOR CONDITION HANDLER FOR 'any_other' SECOND 

I THE 'cleanup' CONDITION IS AN EXCEPTION IN THAT IT DOES NOT 
INVOKE THE any_other HANDLER 
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ACTION TAKEN IF NO ^on unit* IS FOUND ON STACK 

# THERE IS A DEFAULT HANDLER ! def aul t_error — handler^ ? 

• THE PROGRAM, initialize process , HAS ONLY ONE 'on unit 1 (FOR THE 
CONDITION any_other) 

0 THE any_other CONDITION HANDLER CALLS defaul t_error_handler_$wall 

0 defaul t_error_handler_ CHECKS TO SEE WHICH CONDITION WAS SIGNALLED 

II EXECUTES DIFFERENT CODE BASED ON THE CONDITION 

I NOTIFIES USER IF IT WAS NOT SET UP TO HANDLE CONDITION (EXAMPLE: 
USER DEFINED CONDITIONS AND progr am_interr upt 

Q SEVERAL CONDITIONS RESULT IN CALL TO get_to_cl_$ unclaimed_signal 
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ACTION TAKEN IF NO 'on unit' IS FOUND ON STACK 



listen $release stack 



g et_ to_cl_$ un c 1 aim ed_ si g n al 



d e h $wall 



any_other . 2 



signal^ 



pl1_signal_from_ops_ 



user_prog 



command^ processor^ 



abbrev 



listen 



initial ize_process_ 



4 ON UNIT ESTABLISHED FOR any_other 



SIGNAL XYZ 



4 ON UNIT ESTABLISHED FOR any_other 
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ACTION TAKEN IF NO 1 on unit' IS FOUND ON STACK 



0 default error_handler_$wall SETS UP CONDITION HANDLER FOR any_other 
THAT RESULTS IN A CALL TO def aul t_error_handler_$wall_ignore_pi 



Q THUS, A "CONDITION WALL" IS SET UP BETWEEN PROGRAMS RAISING 
CONDITIONS THAT HAVE NO HANDLERS FOR THEM & PROGRAMS RUN AT A 
NEW COMMAND LEVEL THEREAFTER 



I THE WALL IS TRANSPARENT TO THE 1 program_interr upt • AND 'finish 1 
CONDITIONS 
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program interrupt* CONDITION 



m tup occimn r nr\v cad »».^/t«. 2 «; •? »f tc ac unt r nue. 



program_interrupt : pi: proc; 

del program__interrupt condition; 

del signalmen try options (variable); 

del start entry options (variable); 

call signal^ ( "prog ram_ interrupt" , ...); 
if handler^ was_found 
then call "start; 

else call com_err_ (..., " program^ interrupt" , "There is no suspended 

invocation of a subsystem that supports the use of 
this command ." ) ; 

end /* program_interrupt */; 
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program interrupt* CONDITION 



# EXAMPLE DEMONSTRATING THAT 1 program_interrupt ' "PENETRATES THE WALL" 

handler: proc; 
del ( program_interrupt , 



on zerodivide go to A; 

on program_interrupt go to B; 

signal quit; 

A: put skip list ("ZERODIVIDE HAPPENED"); 

put skip; 

B: put skip list ("PROGRAM INTERRUPT HAPPENED"); 

put skip; 

end /* handler */; 



r 14:52 0.153 2 

! handler 
QUIT 

r 14:52 0.265 3 level 2 

! signal zerodivide 

Error: Attempt to divide by zero at signal$i1101 
(> system^ librar y_standard>bound__command_env_) 
system handler for error returns to command level 
r 14:52 0.524 20 level 3 

! signal program interrupt 



del 



quit, 

zerodivide) 
sys print 



condition ; 
file; 



PROGRAM INTERRUPT HAPPENED 
r 14:52 0.221 7 
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o 

o? 

y 

so 

<D 
T» 
1 
O 

a 

o PARTIAL STACK HISTORY OF EXAMPLE 

a> 
a 



en 
i 



ON 



UNCLAIttCO.SIGNAL 



O.I.H.SMIALl 
ANV.OTHERI 



SIGNAL 



Pll_SIG_fROM on 




o 



HANDLERS* 2 



UNCLAIMED .SIGNAL 



WALL.lBNORE.PI. 



ANV.OTHERI 



SIGNAL. 



WALL .IGNORE _K_ 



ANV.OTHERI 



AIIREV 



t tsrf n _ 



UNCLAIMED SIGNAL 



O.E.H.SWALL 



ANY. OTHER 2 



SIGNAL. 



Pll SIGJRGVLQPS. 



HANDLER 



ABBRE W 


SIGNAL 
PROGRAM 

INTERRUPT 




LISIEN_ 





SIGNAL. 
SIGNAL 



e_p_ 

AIIREV 



LISTEN. 



UNCLAIMED. SIGNAL 



tVALL IGNORE _PI . 



ANY OTHER 1 



SIGNAL . 



kVALL IGNORE PI 



ANY OTHER 1 



SIGNAL . 



SIGNAL ' 



ABBREV 



LISTEN. 



UNCLAIMED SIGNAL 



0_E_H.SWAll 



ANY .OTHER 2 



SIGNAL. 



PLLSIG..FRQM_OPS_ 



HANDLER 



ABBREV 



LISTEN. 



INIT.PROC. 



AIIREV 



LISTEN. 



INIT.PROC. 



-1 
o 

LTQ 
01 

B 

H* 
9 
d- 
n> 

*i 
c 
t> 
ct 



o 
o 
as 



o 
=5 



1 program interrupt* CONDITION 



• NOTE: »any_other' CONDITION HANDLERS SHOULD PASS ON THE 
1 program interrupt' CONDITION (SEE continue_to_signal_ AND 
find condition info ) 
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SUMMARY OF CONDITION HANDLING MECHANISM 



CONDITION X RAISED 



EXAMINE MOST 

RECENT 

ACTIVATION 







EXAMINE NEXT 

PREVIOUS 

ACTIVATION 



* 



IS THERE A HANDLER 
ESTABLISHED IN THIS 
ACTIVATION FOR 
CONDITION X? 



NO 



I 



YES 



INVOKE THE 
HANDLER 



YES 





IS THERE A DEFAULT 
HANDLER ESTAB- 
LISHED IN THIS 
ACTIVATION FOR 
ANY OTHER? 


^ NO 


NO 


IS THIS THE 

OLDEST 

ACTIVATION? 




)jj YES 




NO HANDLER 
FOR THIS 
CONDITION 




YES 



DOES HANDLER 
WANT SEARCH 
CONTINUED? 



NO 



RETURN 
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REVIEW OF PL/I DEFINED CONDITIONS 





Default Error 
Handler Signals 
Error 


Undefined if hit 
end of On Unit 


Can be Enabled/ 
Disabled 


Disabled by 
Default 


3CB3 


X 


v 
A 






arrnr 


VAJ 


Y 
/\ 








Y 
A 


Y 
/\ 






fiyerinvprfinw 


Y 
A 


Y 
A 


A 




OVcrTlOW 


X 


A 


X 




CI70 


v 


Y 
A 


v 
A 


v 

A 




Y 
A 


V 
A 


Y 
A 


Y 
A 


subscriptrange 


x 


x 


x 


x 


zerodivida 

4wl WU III V*v* 


Y 
A 


Y 
/\ 


Y 

A 




conversion 

WW! If Wl wlWI 1 


Y 
A 




Y 
A 




endfile 


X* 








key 


X 








record 


X 








transmit 


X 




e 




undefined file 


X 








underflow 






X 




stringsize 






X 


X 


name 










end page 










finish 











NOTE THAT THE 'size' CONDITION IS ENABLED DURING PL/I I/O 
(pl1 signal from_ops ), AND CONSEQUENTLY, A PL/I PROGRAM WHICH IS 
EXECUTING r put f STATEMENTS TO THE 'sysprint' FILE MAY CAUSE 'size' 
CONDITIONS TO BE SIGNALLED EVEN THOUGH THE CONDITION IS NOT ENABLED IN 
THE PROGRAM ITSELF 
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REVIEW OF PL/I DEFINED CONDITIONS 



• CONDITIONS IN THE PRECEDING TABLE WERE COVERED IN EARLIER COURSES, 
HOWEVER, THE 'finish', 'area' AND 'storage' CONDITIONS ARE COVERED 
BELOW SINCE THEY ARE NOT USUALLY FULLY UNDERSTOOD IN AN INTRODUCTORY 
COURSE 



I 'finish' CONDITION 

I THE FINISH CONDITION IS SIGNALLED JUST PRIOR TO RUN UNIT OR 
PROCESS TERMINATION 

II IT IS SIGNALLED BY A STOP STATEMENT OR BY COMMANDS SUCH AS 
'stop_ run', 'logout' AND 'new_proc' 

Q IT BEHAVES JUST LIKE » program_interr upt ' IN THAT IT "PENETRATES 
THE WALL" 

0 ALL CONDITION HANDLERS, WHETHER THEY HANDLE 'finish' OR NOT, 
SHOULD PASS THIS CONDITION ON (BY CALLING continue to_signal_J 
SO THAT ALL PROGRAMS WILL BE NOTIFIED OF THE IMPENDING PROCESS, 
OR RUN UNIT, DESTRUCTION 
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REVIEW OF PL/I DEFINED CONDITIONS 



0 'area* CONDITION 



I AN ATTEMPT HAS BEEN MADE TO ALLOCATE STORAGE IN A PL/I •area* 
VARIABLE WHICH DOES NOT HAVE SUFFICIENT STORAGE FOR THE ATTEMPTED 
ALLOCATION 



I PRINTS A MESSAGE AND SIGNALS THE ERROR CONDITION 



I EXAMPLE 



del (p,q,r) ptr; 

del ( A, B) (1000) fixed bin based; 
del C area(2000) static; 
del d float bin based; 

• • • 

allocate A set(p) in(C); 

• • • 

allocate d set(q) in( C) ; 

• • • 

allocate B set(r) in(C); 

/* causes 'area* condition (unless intervening 
1 f r ee ' statements were executed) */ 



Q 'storage' CONDITION 



S AN ATTEMPT HAS BEEN MADE TO GROW A STACK SEGMENT PAST ITS 
MAXIMUM LENGTH 



I GENERALLY OCCURS AS A RESULT OF ATTEMPTING TO GENERATE A LARGE 
AMOUNT OF 'automatic' STORAGE, OR AS A RESULT OF A RUNAWAY 
RECURSIVE PROCEDURE 



5 IS ALSO SIGNALLED IF A PL/I PROGRAM OVERFLOWS THE SYSTEM FREE 
STORAGE AREA 
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SOME SYSTEM-DEFINED CONDITIONS 



• THE MULTICS SYSTEM HAS DEFINED SOME CONDITIONS OF ITS OWN 



• SOME OF THE USEFUL SYSTEM-DEFINED (NON-PL/I) CONDITIONS ARE LISTED 
BELOW: 



II active^ function^ error , command_error 



0 ARE SIGNALLED BY THE active fnc err AND com_err_ SUBROUTINES 
RESPECTIVELY 



1 DEFAULT HANDLER FOR command error PRINTS A MESSAGE AND RETURNS 



DEFAULT HANDLER FOR active func tion_error PRINTS AN ERROR 
MESSAGE AND RETURNS TO A NEW COMMAND LEVEL 



I cleanup 



0 SIGNALLED TO THOSE PROCEDURES OWNING STACK FRAMES TO BE DISCARDED 
AS A RESULT OF A NON-LOCAL TRANSFER 



I THIS IS A VERY ATYPICAL USE OF THE CONDITION MECHANISM, SINCE 
•cleanup' IS SIGNALLED IN EVERY FRAME BETWEEN THE CURRENT 
STACK FRAME AND THE FRAME CONTAINING THE TARGET OF THE NON-LOCAL 
TRANSFER 

I TYPE OF THING USUALLY DONE IN A 'cleanup' HANDLER 

I CLOSE FILES WHICH HAD BEEN OPENED IN THAT ACTIVATION BLOCK 
1 FREE ALLOCATED 'controlled' OR 'based' VARIABLES 

0 REINITIALIZE STATIC VARIABLES 

1 SHOULD NOT DO A NON-LOCAL ' goto ' 

0 THIS WOULD INTERFERE WITH THE ONE ALREADY IN PROGRESS 
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SOME SYSTEM-DEFINED CONDITIONS 



fl fault_tag_1 

I SIGNALLED WHEN AN ATTEMPT IS MADE TO ACCESS THROUGH AN 
UNINITIALIZED POINTER OR A POINTER CONTAINING INVALID DATA 

I illegal^ opcode , ill eg al_ procedure 

fl SIGNALLED WHEN AN ATTEMPT IS MADE TO EXECUTE AN INVALID OR 
PRIVILEGED MACHINE INSTRUCTION 

I linkage_error • 

0 SIGNALLED WHEN THE DYNAMIC LINKING MECHANISM OF MULTICS CAN 
NOT LOCATE AN EXTERNAL OBJECT 

I. lockup 

n SIGNALLED WHEN A PROGRAM IS EXECUTING A TIGHT LOOP OF CODE 
FOR TOO LONG A TIME 

I null_ pointer 

fl SIGNALLED WHEN AN ATTEMPT IS MADE TO USE AN INVALID (NULL) 
POINTER 

S out-of-bounds 

II SIGNALLED WHEN AN ATTEMPT IS MADE TO REFER TO A LOCATION 
BEYOND THE CURRENT LENGTH OF A SEGMENT 



Not To 



Be Reproduced 



6-23 



F15C 



SOME SYSTEM-DEFINED CONDITIONS 



Q program^ interrupt 

0 SIGNALLED WHEN THE USER HAS ISSUED THE 'program interrupt' 
COMMAND 



I quit 



SIGNALLED WHEN THE USER HITS THE 'break' OR 'attention' KEY 
ON HIS/HER TERMINAL (THE DEFAULT HANDLER PRINTS THE WORD "QUIT" 
ON THE USER'S TERMINAL, ABORTS THE PROGRAM, AND ESTABLISHES A 
NEW COMMAND LEVEL) 



0 IN GENERAL, USER PROGRAMS SHOULD NOT HANDLE THE 'quit' CONDITION 



I record_quota_ over flow 



SIGNALLED WHEN A USER ATTEMPTS TO ALLOCATE A RECORD IN SECONDARY 
STORAGE WHICH WILL OVERFLOW HIS/HER ALLOTTED LIMIT 



5 seg_faul t_error 

0 SIGNALLED WHEN AN ATTEMPT IS MADE TO USE A POINTER WITH AN 
INVALID SEGMENT NUMBER, AND CAN BE CAUSED BY: 

I THE DELETION OR TERMINATION OF A SEGMENT AFTER THE POINTER 
IS INITIALIZED 

I THE POINTER IS NOT INITIALIZED IN THE CURRENT PROCESS 
I THE USER HAS NO ACCESS TO THE SEGMENT 
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SOME SYSTEM-DEFINED CONDITIONS 



YOU ARE NOW READY FOR WORKSHOP 
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Topic VII THE MULTICS I/O SYSTEM Topic VII 

OBJECTIVES: 

Upon completion of this topic* students should be able to! 

1. Define the following terms! 

I/O switch 
I/O module 
stream I/O 

record sequential I/O 
record blocked I/O 
indexed I/O 

2. List the more popular I/O modules. 

3. List the steps required to perform I/O. 

4. Describe an I/O control block (IOCS). 
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CHARACTERISTICS 



• THE MULTICS INPUT/OUTPUT SYSTEM IS A FLEXIBLE, GENERALIZED I/O SYSTEM 
CAPABLE OF SUPPORTING SEVERAL PROTOCOLS OF DATA TRANSMISSION TO A 
FULL COMPLEMENT OF FILES AND DEVICES 



• I/O SYSTEM BASIC CHARACTERISTICS: 

II LOGICAL INPUT/OUTPUT REQUESTS ARE USED RATHER THAN DEVICE-SPECIFIC 
PHYSICAL REQUESTS 

II DEVICE INDEPENDENCE IS ACHIEVED VIA THE MULTICS I/O SWITCH MECHANISM 

S UNFAMILIAR OR NEW DEVICES CAN BE ADDRESSED VIA THE IMPLEMENTATION 
OF SITE-PREPARED INPUT/OUTPUT INTERFACE MODULES 
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THE MULTICS I/O MECHANISM 



THE I/O MECHANISM USES THE FOLLOWING CONSTRUCTS: 

I SWITCH, SWITCHNAME 

I A SWITCH IS A LOGICAL CONSTRUCT USED TO DESIGNATE THE TARGET 
OF AN INPUT OR OUTPUT REQUEST 

I ASSOCIATED WITH AN I/O SWITCH IS A "SWITCHNAME" 

Q ALL I/O REQUESTS ARE DIRECTED TO A "SWITCH" WHICH IS "ATTACHED" 
BY A DEVICE-DEPENDENT PROGRAM, CALLED AN I/O MODULE, TO A 
PARTICULAR DEVICE OR FILE 

I THE SUPPORTING DATA STRUCTURE OF A SWITCH IS AN I/O CONTROL 
BLOCK (IOCB) 

0 INPUT/OUTPUT MODULE 

I A DEVICE-DEPENDENT COMMUNICATION MODULE WHICH ACTS AS THE 
INTERFACE BETWEEN THE USER'S LOGICAL I/O REQUESTS AND THE 
HARDWARE-LEVEL I/O SYSTEM 

I TRANSLATES THE USER 1 S LOGICAL REQUESTS INTO THE PHYSICAL REQUESTS 
APPROPRIATE TO THE TYPE OF DEVICE OR FILE FOR WHICH IT WAS 
WRITTEN 

I SYSTEM STANDARD MODULES SUPPORT I/O TO/FROM BASIC DEVICES (TAPE, 
REMOVABLE DISK, TERMINAL DEVICES, CARD READERS, ETC.) AND 
FILES (SEGMENTS IN THE VIRTUAL MEMORY) 
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THE MULTICS I/O MECHANISM 
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THE MULTICS I/O MECHANISM 
PROTOCOLS SUPPORTED 



FOUR BASIC I/O PROTOCOLS (FILE STRUCTURES) SUPPORTED 



I THE TYPE OF PROTOCOL BEING USED LIMITS THE REQUESTS THAT CAN BE 
SATISFIED 



I CERTAIN I/O MODULES SUPPORT ONLY ONE PROTOCOL, SOME I/O MODULES 
SUPPORT ALL THE PROTOCOLS 



I THEY ARE: 

1 1) STREAM INPUT/OUTPUT 

S A STREAM FILE IS A SEQUENCE OF ASCII CHARACTERS, SEPARATED 
BY NEW LINE AND NEWPAGE CHARACTERS 

I OFTEN CALLED AN "UNSTRUCTURED" FILE 

I EXAMPLES: TERMINAL DIALOG, TEXT EDITOR CREATED SEGMENTS, 
TAPES WRITTEN VIA tape_mult_ 

0 2) RECORD SEQUENTIAL INPUT/OUTPUT 

I A "STRUCTURED" FILE OF VARIABLE LENGTH RECORDS, EACH RECORD 
REPRESENTING ONE STRUCTURE 

I A RECORD FILE MAY BE ACCESSED IN "SEQUENTIAL" PROTOCOL, 
WHICH MEANS THAT THE CURRENT RECORD AND NEXT RECORD ARE 
WELL-DEFINED 

I EXAMPLES: TAPES WRITTEN VIA tape_ibm_ OR tape_ansi , CERTAIN 
VIRTUAL MEMORY SEGMENTS 
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THE MULTICS I/O MECHANISM 
PROTOCOLS SUPPORTED 

D 3) RECORD BLOCKED IN PUT/ OUT PUT 

1 A RECORD FILE MAY BE CREATED IN LOGICAL BLOCKS, THUS ALLOWING 
I/O TO BE DONE A BLOCK AT A TIME 

I BLOCK SIZE IS FIXED 

I A BLOCK CONTAINS 

I ONE RECORD (WITH POTENTIAL WASTED SPACE) IF IN A VIRTUAL 
MEMORY FILE 

I ONE OR MORE RECORDS IF ON ANSI OR IBM TAPE 
I SPECIFY BLOCKED MODE AT ATTACH TIME 

I 4) INDEXED INPUT/OUTPUT 

I AN INDEXED FILE IS A "KEYED" FILE, IMPLEMENTED AS A 
MULTI-SEGMENT FILE WITH ONE (OR MORE) COMPONENTS HOLDING 
THE "KEY VALUES", AND ONE (OR MORE) COMPONENTS HOLDING THE 
"DATA RECORDS" 

Q AN INDEXED FILE MAY BE ACCESSED IN EITHER "KEYED SEQUENTIAL" 
MODE, OR "KEYED DIRECT" MODE 

i MUST BE IN THE VIRTUAL MEMORY 

II EXAMPLE: "RELATIONS" IN A MRDS DATABASE 

I PL/I DEDUCES THE PROTOCOL BY EXAMINING LANGUAGE I/O STATEMENTS 
AND/OR THE ATTACH DESCRIPTION 
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THE MULTICS I/O MECHANISM 
THE MORE POPULAR I/O MODULES 



SOME OF THE SYSTEM STANDARD I/O MODULES, THEIR FUNCTIONS, AND THE 
PROTOCOLS SUPPORTED ARE: 



NAME 

1) vfile_ 

2) tty_ 

3) discard^ 

4 ) syn_ 

5) rdisk_ 

6) record — stream_ 

7) -tape_ mult — 

8) tape_ ibm_ 
tape_an si_ 

9) tape_nstd_ 

10) bisync_ 

11) audit 



FUNCTION 

I/O TO/ FROM SEGMENTS IN 
THE VIRTUAL MEMORY 

I/O TO/ FROM TERMINAL 
DEVICES 

OUTPUT SINK 

ALLOWS ONE SWITCH TO SERVE 
AS A SYNONYM FOR ANOTHER 
SWITCH 

I/O TO/ FROM REMOVABLE, NON- 
MULTICS DISK PACKS 



ALLOWS RECORD I/O OPERATIONS 
TO BE DIRECTED TO A STREAM 
FILE AND VICE VERSA 

I/O TO/FROM A MULTICS 
FORMAT TAPE 

I/O TO/ FROM A TAPE FILE IN 
IBM OR ANSI FORMAT 

I/O TO/FROM TAPES IN NON-STANDARD 
OR UNKNOWN FORMATS 

I/O ACROSS A BINARY SYNCHRONOUS 
COMMUNICATIONS CHANNEL 

INTERCEPTS I/O ACTIVITY ON A 
GIVEN SWITCH, ALLOWING LOGGING 
AND EDITING OF DATA 



PROTOCOLS SUPPORTED 



ALL 



STREAM 



ALL 



ALL 



SEQUENTIAL, 
KEYED, OR 
BLOCKED 

STREAM 
<-> 

SEQUENTIAL 
STREAM 



SEQUENTIAL, 
BLOCKED 

SEQUENTIAL 

STREAM 

STREAM 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 



STEPS REQUIRED TO PERFORM I/O 



I 1) THE SPECIFIED SWITCH MUST BE "ATTACHED" (INITIALIZED) BY A 
SPECIFIED I/O MODULE TO SOME TARGET DEVICE OR FILE (SUBSEQUENT 
REQUESTS DIRECTED TO THE SWITCHNAME OPERATE VIA THE I/O MODULE 
ON THE TARGET DEVICE OR FILE) 



0 2) THE SWITCH MUST BE "OPENED" IN A MODE COMPATIBLE WITH THE 
TYPE OF DEVICE OR FILE BEING MANIPULATED 



1 3) INPUT/OUTPUT OPERATIONS CAN NOW BE DIRECTED TO THE SWITCH 
(OPERATIONS MUST BE CONSISTENT WITH THE ATTACHMENT AND OPENING 
MODE OF THE SWITCH) 



fl 4) THE SWITCH MUST BE "CLOSED" LEAVING THE SWITCH IN THE STATE 
IT WAS PRIOR TO THE "OPENING" (THAT IS, IT MAY NOW BE OPENED 
WITH A DIFFERENT MODE) 



11 5) THE SPECIFIED SWITCH MUST BE "DETACHED" BREAKING THE ASSOCIATION 
BETWEEN THE SWITCHNAME AND THE I/O MODULE AND TARGET (HENCE, THE 
SWITCH MAY BE ATTACHED IN A NEW WAY) 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 




ATTACH 



SWITCH 


OPEN 


SWITCH 


CLOSE 


IOCB 


MODE 2 ^ 


IOCB 





/ 7 /* 





DETACH 


SWITCH 


CLOSE 


SWITCH 


OPEN 


SWITCH 




IOCB 




IOCB 


MODE 1 


IOCB 





7 / / / 

/ / / / 
ft/' 



O O 



SWITCH 


ATTACH 


SWITCH 


OPEN 


IOCB 




IOCB 


MODE I 31 




\ \ \ \ 

\ \ \ \ 
\ \ \ \ 



SWITCH 


ETC. 


IOCB* 





o o 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 

ALL I/O OPERATIONS CAN BE PERFORMED AT THREE BASIC LEVELS: 

II LANGUAGE LEVEL - 'open*, 1 close', 'get', 'read', 'put', 'write 

0 COMMAND LEVEL - THE 'io_call' COMMAND 

1 SUBROUTINE LEVEL - THE *iox_» SUBROUTINE 

I EXAMPLES (THE FOLLOWING ARE EQUIVALENT): 
fl PL/I 

open file ( x) title ( l, vfile_ user_file") stream output; 

IT r> nMM a >tn t puct 

io_call attach x vfile_ user__file 
io~call open x str eam__ output 

0 SUBROUTINE LEVEL 

call iox_ $attach_naiae ("x", iccb_ptr , n vfil8_ user_file" , 

ref — ptr, code); 
call iox_$open ( iocb^ptr , 27 "0"b, code); 

I LANGUAGE VS. I/O SYSTEM 



PL/I STATEMENT 


EQUIVALENT I/O CALLS 


open 


attach 




open 


crose 


close 




detach 
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THE MULTICS I/O MECHANISM 



PERFORMING MULTICS I/O 



• THE ATTACHMENT AND DETACHMENT OF A SWITCH CAN BE PERFORMED EITHER 
EXTERNALLY TO A PROGRAM OR INTERNALLY BY THE PROGRAM ITSELF 



I IF THE SWITCH IS ATTACHED EXTERNALLY, THE PROGRAM RECOGNIZES 
THIS ATTACHMENT, HONORS THIS PRIOR ATTACHMENT, AND IGNORES THE 
SPECIFIED INTERNAL ATTACH DESCRIPTION (THUS YIELDING DEVICE 
INDEPENDENCE) 



0 IF THE SWITCH HAS NOT BEEN ATTACHED EXTERNALLY, THE ATTACH 
DESCRIPTION SUPPLIED BY THE PROGRAM (EITHER EXPLICITLY OR 
IMPLICITLY) WILL BE USED TO ATTACH THE SWITCH 



I IF THE SWITCH IS ATTACHED EXTERNALLY, IT MUST BE DETACHED EXTERNALLY 

I IF THE SWITCH- IS ATTACHED INTERNALLY BY EXECUTION OF THE 'open' 
STATEMENT, IT WILL BE DETACHED BY EXECUTION OF THE 'close' 
STATEMENT 



• THE ABOVE STATEMENTS SIMILARLY APPLY TO THE OPEN AND CLOSE OPERATIONS 
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THE MULTICS I/O MECHANISM 
PERFORMING MULTICS I/O 



0 EXAMPLE 



x: proc; 




del line char(80 ) ; 
del (abc, xyz) file; 
del i ; 




open file (abc) input; 
open file (xyz) output; 




do i = 1 to 50; 

get file (abc) list 
put file (xyz) list 

end; 


( line) ; 
( line) ; 


close file (abc), file 


( xyz) ; 


end /* x */; 





i TO HAVE OUTPUT. SENT TO TERMINAL INSTEAD OF FILE xyz USER COULD 
TYPE THE FOLLOWING: 



io call attach xyz syn user__output 



! . io call detach xyz 
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THE f iox ' SUBROUTINE 



• iox IS THE USER-RING INTERFACE TO THE MULTICS IN PUT/ OUT PUT SYSTEM 



II ALL I/O OPERATIONS ISSUED AT THE USER-RING LEVEL (WHETHER FROM 
COMMAND LEVEL, LANGUAGE LEVEL, OR DIRECT iox_ CALL) RESULT IN A 
CALL TO iox 



0 iox PROVIDES ENTRY POINTS FOR ALL INPUT/OUTPUT OPERATIONS 



EVERY iox_ ENTRY POINT REQUIRES AN ARGUMENT DENOTING THE PARTICULAR 
I/O SWITCH (ACTUALLY THE IOCB) INVOLVED IN THE OPERATION 



I IF AN ENTRY POINT REQUIRES THE I/O SWITCH TO BE OPEN, AND IF IT 
IS NOT, THE CODE • error_table_$ not_open ' IS RETURNED 



I IF THE I/O SWITCH IS OPEN, BUT THE OPERATION IS NOT ALLOWED FOR 
THAT OPENING MODE, THE CODE ' error_table_$ reoperation » IS RETURNED 
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THE ; iox * SUBROUTINE 

• THE MAJOR ENTRY POINTS OF iox_ CAN BE CLASSIFIED AS FOLLOWS: 

I ATTACHING/DETACHING 
I iox_ $attach_name 
fl iox_ $attach_ptr 

fl iox_$detach_iocb 

Q iox_$destroy_iocb 

fl iox_$ find_ iocb 

fl iox_$ loo k__ iocb 

fl iox_$move_attach 

fl OPENING/CLOSING 
D iox_$open 
fl iox_$ close 

II STREAM I/O REQUESTS 
I iox_$ get_char s 

Q iox_ $get_ line 
fl iox $put chars 
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THE 'iox ' SUBROUTINE 



3 RECORD I/O REQUESTS 

I iox_$delete — record 
fl iox_ $read_key 

II iox_$read_ length 
Q iox_$read_record 

fl iox — $rewrite — record 

fl iox_$ seek_key 

fl iox_$wr i te__record 

II CONTROL REQUESTS 
5 iox_$ control 
fl iox_$ modes 
II iox $position 
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I/O CONTROL BLOCKS 

WHAT IS AN I/O CONTROL BLOCK (IOCB)? 

0 EVERY SWITCHNAME HAS ASSOCIATED WITH IT AN •IOCB» 

0 AN 'IOCB* IS A STANDARD DATA STRUCTURE 

II IT IS THE PHYSICAL REALIZATION OF A SWITCH 

1 THEY ARE FOUND IN THE USER'S PROCESS DIRECTORY 

I AN »IOCB' IS CREATED BY iox WHEN A SWITCHNAME IS USED IN AN 
"ATTACH STATEMENT" OR " ATTACH COMMAND" FOR THE FIRST TIME IN A 
PROCESS 

II IF THE SAME SWITCHNAME IS USED LATER IN THE PROCESS, THE SAME 
f IOCB' IS REUSED 

I THUS THERE IS A ONE TO ONE MAPPING BETWEEN SWITCHNAMES AND 
IOCB'S 

I ONCE AN 'IOCB* IS CREATED, IT LIVES THROUGHOUT THE PROCESS (UNLESS 
EXPLICITLY DELETED) 
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I/O CONTROL BLOCKS 



/* BEGIN INCLUDE FILE ..... iocb.incl.pl1 

13 Feb 1975, M. Asherman */ 
/* Modified 11/29/82 by S. Krupp to add new entries and 

to change version number to 10X2. */ 

/* format: style2 */ 

del 1 iocb aligned based, 

/* I/O control block. */ 
2 version character (4) aligned, 

/* 10X2 */ 
2 name char (32) , 

/* I/O name of this block. */ 
2 actual^ iocb_ ptr ptr , 

/« IOCB ultimately SYNed to. */ 
2 attach^ descrip_ptr ptr, 

/* Ptr to printable attach description. */ 
2 attach_data_ptr ptr, 

/* Ptr to attach data structure. */ 
2 open_descrip_ptr ptr, 

/* Ptr to "printable open description. */ 
2 open — data__ptr ptr , 

/■•""Ptr "to open data structure (old SDB) . */ 
2 reserved bit (72), 

/* Reserved for future use. */ 
2 detach — iocb entry (ptr, fixed (35)), 

/• detach_ iocb( p,s) */ 
2 open entry (ptr, fixed, bit (1) aligned, 

fixed (35)) , 
/• open( p , mode ,not__ used ,s) */ 
2 close entry (ptr, fixed (35)), 

/* close(p,s) •/ 
2 get_line entry (ptr, ptr, fixed (21), 

fixed (21 ) , fixed (35)) , 
/* get_ line( p,buf ptr ,buflen ,actlen ,s) */ 
2 get char's entry (ptr, ptr, fixed (21), 

fixed (21 ) , fixed (35)) , 
/* get_chars( p,buf ptr ,buflen ,actlen ,s) */ 
2 put chars entry (ptr, ptr, fixed (21), 

fixed (35)) , 
/* put -> chars( p,buf ptr ,buf len ,s) */ 
2 modes ~ entry (ptr, char (*), char (*), 

fixed (35)) , 
/* modes( p,newmode ,oldmode ,s) */ 
2 n o si tion ent-r v ( n t-r fixed fixed (21) 

* fixed" (35)) ," 
/• position( p,u 1 ,u2,s) */ 
2 control entry (ptr, char (*), ptr, 

fixed (35)) , 
/* controK p, order ,infptr ,s) •/ 
2 read record entry (ptr, ptr, fixed (21), 

fixed (21 ) , fixed (35)) , 
/• read_record( p,buf ptr ,buflen ,actlen ,s) •/ 
2 write_record entry (ptr, ptr, fixed (21), 



Not To Be Reproduced 



7-16 



F15C 



I/O CONTROL BLOCKS 



fixed (35)) , 
/* write_record( p,buf ptr ,buflen ,s) */ 
2 rewrite record .entry (ptr, ptr, fixed (21), 

fixed (35)) , 
/* rewrite^ record( p,buf ptr ,buflen ,s) */ 
2 delete_reeord entry (ptr, fixed (35)), 

/* deiete — record( p,s) */ 
2 seek_key entry (ptr, char (256) varying, 

fixed (21 ) , fixed (35)) , 
/* seek_key( p,key,len ,s) */ 
2 read_key entry (ptr, char (256) varying, 

fixed (21 ) , fixed (35)) , 
/* read_key( p,key,len ,s) */ 
2 read_length entry (ptr, fixed (21), fixed (35)), 

/*~read_length( p,len ,s) */ 
2 open_file entry (ptr, fixed bin, char (*), 

bit (1) aligned, fixed bin (35)), 
/* open_ file( p, mode ,desc ,not__ used ,s) */ 
2 close_file entry (ptr, char (*), fixed bin (35)), 

/* close_file( p,desc ,s) */ 
2 detach entry ( ptr , char (*), fixed bin (35)); 

/* detach( p ,desc ,s) */ 

declare iox_ $ iocb_ version^ sentinel 

~" character (4) aligned external static; 

/» £mt) INCLUDE FILE ..... iocb .incl .pll */ 

del 1 attach__descrip based aligned, 
2 length fixed bin (17), 

2 string char (0 refer ( attach_descrip .length) ) ; 
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I/O CONTROL BLOCKS 



AN ATTACH DESCRIPTION IS A CHARACTER STRING CONVEYING THE FOLLOWING 
INFORMATION: 

I MODULE NAME 

I MODULE-SPECIFIC ARGUMENTS, SUCH AS: 
1 PATHNAME (vfilej 
Q CHANNEL NAME (tty_, bisync_) 

Q VOLUME ID ( tape_ibra_ , tape_ ansi_, tape_mult_, tape_nstd_) 
0 DISKJ)RIVE_ID AND PACK_ID (rdiskj 
Q SWITCHNAME (syn_, r ecord_stream_) 

Q MODULE-SPECIFIC CONTROL ARGUMENTS, SUCH AS: 
H -extend (vfile_, tape_ibm_, tape_ansi_) 
Q -density (tape_ ibm — , tape_ansi_, tape_mult_) 
0 -block ( tape_ibm_ . tape_ ansi_) 
Q -blocked (vfile_) 

fl COMPLETE DESCRIPTIONS OF THE I/O MODULES AND THE ARGUMENTS SPECIFIED 
AT ATTACH TIME ARE IN Multics Subroutines & I/O Modules (AG93) 
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I/O CONTROL BLOCKS 



• THE PRINCIPAL COMPONENTS OF AN 'IOCB' ARE 'pointer* VARIABLES AND 
'entry' VARIABLES 



• THERE IS ONE 'entry' VARIABLE FOR EACH I/O OPERATION, WITH THE 
EXCEPTION OF THE ATTACH OPERATION 



• TO PERFORM AN I/O OPERATION THROUGH THE SWITCH, THE APPROPRIATE 
ENTRY VALUE IN THE CORRESPONDING 'IOCB' IS CALLED 



I FOR EXAMPLE: 



call iox_$ put_chars( iocb_ptr , 



); 



CAN BE THOUGHT OF AS: 



call iocb_ptr->iocb ,put_char s( 



); 
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I/O CONTROL BLOCKS 



# WHEN iox $ attach name IS CALLED IT: 



I CREATES/LOCATES THE , IOCB» ASSOCIATED WITH THAT SWITCHNAME 



I INITIALIZES SOME OF THE ELEMENTS IN THE •IOCB* STRUCTURE 



I CALLS <module n am e>$< module name) attach 



D THUS THERE NEED BE NO ENTRY FOR THE ATTACH OPERATION IN THE 
»IOCB f 



Q THIS ENTRY POINT IN THE I/O MODULE FINISHES THE INITIALIZATION 
OF THE •IOCB 1 

fl FOR EXAMPLE, IF THE I/O MODULE INVOLVED IN THE ATTACHMENT WAS 
vfile_: 

I vfile_$vfile_attach IS CALLED 

I AFTER THE ATTACHMENT (INITIALIZATION) IS COMPLETE: 
1 iocb.open CONTAINS THE ENTRY TO vfile_$open 
Q iocb .close CONTAINS THE ENTRY iox $ err_not_open 
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I/O CONTROL BLOCKS 



• AFTER THE ATTACHMENT OF THE SWITCH, EVERY I/O OPERATION ON THAT 
SWITCH REFERENCES THE CORRESPONDING 'IOCS' TO FIND THE ENTRY POINT 
AT WHICH TO START EXECUTION 



I ONE OF TWO ACTIONS MAY RESULT: 



I iox GENERATES AN ERROR MESSAGE (IF IT IS AN ILLEGAL OPERATION) 



Q EXECUTION STARTS AT THE APPROPRIATE ENTRY POINT OF THE 
APPROPRIATE MODULE 

S THIS EXECUTION UPDATES THE 'IOCB', USUALLY REPLACING SOME 
ENTRY VALUES CAUSING ERROR MESSAGES WITH ENTRY VALUES 
INDICATING ENTRY POINTS IN THE MODULE (AND VISA VERSA) 



0 EXAMPLE 


(IN THE 


ABOVE CASE): 




IOCB 


MEMBER 


BEFORE OPENING 


AFTER OPENING 


iocb 


.open 


vfile — $open 


iox_ $ er r_no t_cl o sed 


iocb 


•close 


iox_$ err_ not_open 


vfile_$ close 



• IT IS THE RESPONSIBILITY OF THE I/O MODULE TO MAINTAIN THE ACCURACY 
OF THE 'IOCB' 



• ONLY THE iox ENTRY POINTS RESULTING IN ATTACHMENT OF A SWITCH 
REQUIRE THE MODULE AS AN INPUT ARGUMENT 



I AFTER THAT TIME, THE 'IOCB' "POINTS TO" THE APPROPRIATE ENTRY 
POINTS IN THE APPROPRIATE MODULE (THE USER NEED ONLY PROVIDE A 
POINTER TO THE 'IOCB') 
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I/O CONTROL BLOCKS 



# IN VIEW OF THE ABOVE DISCUSSION OF IOCB'S AND SWITCHES, THE TERM 
"SWITCH" SHOULD MAKE MORE SENSE 



I A SWITCH/IOCB CAN BE THOUGHT OF AS A STRUCTURE CONTAINING TRANSFER 
VECTORS 



YOU ARE NO'W READY FOR WORKSHOP 
#5 
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The iox Multics Subroutine 
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Topic VIII THE IOX_ SUBROUTINE Topic VIII 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1. Open and close I/O switches usins iox_. 

2. Read data from the user's terminal. 

3. Display information on the user's terminal. 

4. Read and write stream files. 

5. Read and write sequential and keyed files. 



Multics 
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INTRODUCTION TO USING iox 

# WHY USE iox_ RATHER THAN PL/I I/O STATEMENTS? 

0 iox_ IS MORE EFFICIENT 

I WRITTEN IN aim 

0 NUMBER OF MEMORY ACCESSES 
& iox_ ACCESSES »IOCB» ONLY 

I PL/I STATEMENTS ACCESS 'FSB' (FILE STATE BLOCK) AND l IOCB t 

0 MORE POWERFUL 

1 BETTER ERROR DETECTION 

1 ACCEPTED CONVENTION FOR SYSTEM CODE 

# WARNING: SHOULD NOT MIX iox AND PL/I I/O DUE TO INCONSISTENCIES 
(DIRECT CALLS TO iox DO NOT MAINTAIN »FSB f ) 
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iox OPENING MODES 



• iox OPENING MODES SUPPORTED AND THE iox OPERATIONS PERMITTED FOR 
EACl OPENING: 



NO 



NAME 



I/O OPERATIONS PERMITTED 



1 stream — input 

2 stream~output 

3 stream~input__ output 

4 sequential^ input 

5 sequential~output 

6 sequential" in put_ output 

7 sequential_update 

8 keyed — sequential^ input 

9 keyed_sequential_output 

10 keyed_sequential_update 

11 direct^ input 

12 direct__output 
1 3 . direct~update 



get_line, get_chars, position 
put"~chars 

I +~2 

read_record , read_length, position 
write record 
4 + 5"* 

4, rewr ite_ record , delete_record 

read_record , read_length, position, 

"~seek_key, read__key 
seek_key, write_record 
8 + 9 , rewr ite_record ,delete__ record 

read_record , read_length, seek_key 
seek_key, write — record 

I I +~1 2, rewr ite — record ,delete_record 



SEE >ldd> include> iox_modes .incl ,pl1 



• NOTE : 



I THE 'open' , 'close 1 , 'control' , AND 'modes' OPERATIONS ARE PERMITTED 
WITH ANY OPENING MODE 



I THE ABOVE NUMBERS ARE USED IN CALLS TO iox TO SPECIFY OPENING 
MODES 



I THE LONG NAME (AS GIVEN ABOVE) IS USED WITH » io call' 



D PL/I SPECIFIES THE OPENING MODE IN THE FILE DESCRIPTION 
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STANDARD SWITCH ATTACHMENTS 



THE MULTICS STANDARD PROGRAMMING ENVIRONMENT MAKES USE OF FOUR SWITCHES 
WHICH ARE ATTACHED AND OPENED AS PART OF THE PROCESS CREATION CYCLE 



• THE STANDARD ATTACHMENTS ARE: 



user_ i/o tty_ - log in_ channel 

"~ stream_input_output " 
user_ input syn_ user_i/o 

user~output • syn_ user_i/o 
error_output syn_ user_i/o 



• IN TERMS OF iox , THESE SWITCHES ARE IDENTIFIED BY THE FOLLOWING 
DECLARATIONS: 



I del iox_$user_ io external pointer; 
I del iox_$user_ input external pointer; 
I del iox_ $user_ output external pointer; 

I del iox — $error_output external pointer; 

II EXAMPLE 

call iox_ $ put_char s ( iox_$ user_output , buffer_ptr, 

buf fer_ length , code); 
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iox ENTRY POINTS 



• THERE ARE OVER 25 ENTRY POINTS FOR THE iox SUBROUTINE (SEVERAL ARE 
PRESENTED IN THE REMAINDER OF THIS TOPIC) ~ 

• THE FIRST 7 ENTRY POINTS: 

I ARE SUMMARIZED ON THE NEXT 2 PAGES 

1 WILL BE STUDIED IN DETAIL BY REFERRING TO THE SUBROUTINES MANUAL 
I WILL BE USED IN WORKSHOP 6 

I REPRESENT SOME COMMONLY USED ENTRY POINTS THAT WOULD BE USED TO 
PROMPT A USER FOR A KEY AND THEN FIND THE CORRESPONDING RECORD 
IN A KEYED FILE 

• THE OTHER ENTRY POINTS (STARTING ON PAGE 8-7) WILL BE COVERED IN 
MUCH LESS DETAIL 



• SEVERAL OPERATIONS INVOLVE THE USE OF A BUFFER 



0 A BUFFER IS A BLOCK OF STORAGE PROVIDED BY THE CALLER OF THE 
OPERATION AS THE TARGET FOR INPUT OR THE SOURCE FOR OUTPUT 



II A PTR TO THE BUFFER IS PASSED TO iox SUBROUTINES 
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iox ENTRY POINTS 



• iox $ attach name 



fl ACCEPTS A SWITCHNAME 



I RETURNS A POINTER TO THE »IOCB f FOR THE CORRESPONDING SWITCH 



1 ATTACHES THE SWITCH IN ACCORDANCE WITH THE SUPPLIED ATTACH 
DESCRIPTION 



• iox_$open 

0 OPENING MODE IS SPECIFIED BY A NUMBER (SEE PAGE 8-2) 



iox_$get_ line 



fl THE NEW LINE CHARACTER SIGNIFIES THE END OF THE LINE 



I A CODE OF ZERO IS RETURNED ONLY IF A NEWLINE CHARACTER IS READ 



I THE NEWLINE ITSELF IS READ INTO THE BUFFER 
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iox ENTRY POINTS 

• iox — $ seek_key 

S THE NEXT RECORD POSITION AND CURRENT RECORD POSITION ARE SET TO 
THE RECORD WITH THE GIVEN KEY 

I USED BEFORE DOING A read, delete, rewrite, ETC. 
iox_$read_record 

0 READS THE NEXT RECORD IN A STRUCTURED FILE 

1 KEYED READS FIRST REQUIRE A CALL TO iox_$ seek_ke y 

• iox_$ close 

• iox_$detach_iocb 

4 

Q DOES NOT FREE THE IOCS' S STORAGE 
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iox ENTRY POINTS 



• THE REST OF THIS TOPIC WILL SERVE AS AN OVERVIEW OF OTHER iox 
ENTRY POINTS 



iox_ $ attach_ptr 

D call iOx_ $attach_ptr ( iocb_ptr , atd, ref_ptr, code); 



2 BEHAVES LIKE iox_$ attach_name , EXCEPT iocb_ptr IS AN INPUT NOT 
AN OUTPUT VARIABLE 



iox $find iocb 



fl call iox_ $ find_ iocb (switchname, iocb_ptr , code); 



I GIVEN A SWITCHNAME, RETURNS A POINTER TO THE IOCB, BUT DOES NO 
ATTACHMENT (IF THE BLOCK DOES NOT ALREADY EXIST, IT IS CREATED) 



Q iox — $ find_ iocb + iox_$ attach_ptr = iox_$attach_narae 



• iox $look iocb 



D call iox — $ loo k_ iocb (switchname, iocb_ ptr , code); 



BEHAVES LIKE iox $find iocb, HOWEVER DOES NOT CREATE A BLOCK IF 
ONE DOES NOT ALREADY EXIST 
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iop ENTRY POINTS 



• iox $move attach 



Q call iox_ $move_attach ( iocb_ ptrl , iocb_ptr2, code); 



I INCLUDED FOR COMPLETENESS (NOT FOR NOVICE USERS) 



fl MOVES AN ATTACHMENT FROM ONE ATTACHED SWITCH TO ANOTHER DETACHED 
SWITCH 



THE PERFECT EXAMPLE (FOR WHICH move_attach WAS WRITTEN) IS THE 
CASE OF file_output, IN WHICH A TEMPORARY SWITCH IS CREATED, THE 
CURRENT ATTACHMENT OF user_output IS MOVED TO THAT TEMPORARY 
SWITCH, AND THEN user_output IS ATTACHED TO THE OUTPUT FILE. 



iox_$destroy_iocb 

D call iox_ $destroy_iocb ( iocb_ptr , code); 



II FREES THE STORAGE USED BY A DETACHED CONTROL BLOCK 
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iox ENTRY POINTS 



• iox_$get_ chars 

Q call iox_$get_char s ( iocb_ ptr , buff_ptr, n, n_read , code); 

I USER REQUESTS n BYTES (CHARACTERS) FROM A STREAM FILE OR DEVICE 
(ACTUALLY NUMBER READ IS n_read BYTES) 

Q IF n = n_read THEN code = 0 

I IF n_read < n THEN code = error_ table_$ short_record 

0 IF NEXT BYTE IS "END OF FILE" THEN code = error table_$end of info 
(NOTE THAT THE 'endfile' CONDITION IS NOT SIGNALLED WHEN USING 
iox — ) _ 

D READS NEW LINE CHARACTERS INTO BUFFER JUST LIKE ANY OTHER CHARACTER 

II IF n IS GREATER THAN THE SIZE OF THE RECEIVING BUFFER, OVERFLOW 
CHARACTERS WILL BE WRITTEN PAST THE END OF THE BUFFER, YIELDING 
POTENTIALLY DISASTROUS RESULTS 

1 BUFFER OUGHT TO BE EXPLICITLY FLUSHED PRIOR TO CALL, BECAUSE 
JUST n_read CHARACTERS WILL BE OVERWRITTEN 

I ALTERNATIVE: 

del max_buff char (80) based (buff_ptr); 
del buff char (n read) based ( buf f_ ptr); 



Not To Be Reproduced 



8-10 



F15C 



iox ENTRY POINTS 

• iox_$put_ chars 

fl call iox_$put_chars ( iocb_ptr , buff^ptr, n, code); 

I WRITES n BYTES (CHARACTERS) TO THE UNSTRUCTURED FILE OR DEVICE 

I BUFFER SHOULD CONTAIN A NEWLINE, IF ONE IS INTENDED (THERE IS NO 
'put^line* ENTRY POINT) 

0 IF OPEN FOR stream output THE CHARACTERS ARE APPENDED TO THE END 
OF THE FILE. IF OPEN FOR stream input output FILE TRUNCATION 
OCCURS JUST BEFORE THE NEXT BYTE 

• iox_$write_record 

fl call iox_$wr ite_record ( iocb_ ptr , buff_ptr, rec_len, code); 

1 ADDS A RECORD TO A STRUCTURED FILE 

1 IF OPEN FOR sequential_output , THE RECORD IS APPENDED TO THE 
FILE. IF OPEN FOR sequential_input_output , FILE TRUNCATION OCCURS 
JUST BEFORE THE NEXT RECORD 

I iox_$seek_key MUST BE CALLED BEFORE DOING A KEYED WRITE IN ORDER 
TO "SET THE KEY" FOR INSERTION 
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iox ENTRY POINTS 

iox_ $ rewr ite_ record 

fl call iox — $rewrite_record ( iocb_ptr , buff_ptr, rec__len, code); 



I REPLACES THE CURRENT RECORD IN A STRUCTURED FILE THAT HAS BEEN 
OPENED FOR "UPDATE" 



Q IF THE CURRENT RECORD POSITION IS NULL, error table $no record 
IS RETURNED " - - 



I THUS IT IS FIRST NECESSARY TO "LOCATE" THE RECORD TO BE REPLACED 
(USING read_record, seek_key OR position ENTRY POINTS) 



iox_$ read_leng th 

Q call iox_$read_ length ( iocb_ ptr , rec_len, code); 

1 RETURNS THE LENGTH OF THE NEXT RECORD IN A STRUCTURED FILE 



i IF THE NEXT RECORD POSITION IS AT THE END OF FILE, code 
error table $end of info 



fl APPLICATION: TO DETERMINE HOW LONG THE BUFFER MUST BE IN ORDER 
TO HOLD THE NEXT RECORD TO BE READ (EXAMPLE: VARIABLE LENGTH 
RECORDS) 
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iox ENTRY POINTS 



iox $delete record 



fl call iox_$delete_record ( iocb_ptr , code); 



I DELETES THE CURRENT RECORD FROM THE STRUCTURED FILE, WHOSE SWITCH 
MUST BE OPENED FOR "UPDATE" 



Q IF THE CURRENT RECORD IS NULL, code = error_table_$ no_record 



0 AGAIN, IT IS FIRST NECESSARY TO "LOCATE" THE RECORD TO BE DELETED 
(USING read_record, seek_key OR position ENTRY POINTS) 



• iox $read key 



call iox_ $read_key ( iocb_ptr , key, rec_ len , code); 



H RETURNS BOTH THE KEY AND THE LENGTH OF THE NEXT RECORD IN AN 
INDEXED FILE 



I code = error table_$end of info IF THE NEXT RECORD POSITION IS 
AT THE END OF" FILE 



I code = error_table_$no_record IF THE NEXT RECORD POSITION IS 
NULL 
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iox ENTRY POINTS 



iox_$ position 

D call iox_$ position ( iocb__ ptr , type, n, code); 

I POSITIONS TO THE BEGINNING OR END OF A FILE, OR SKIPS FORWARD OR 
BACKWARD OVER A SPECIFIED NUMBER OF LINES OR CHARACTERS 
(UNSTRUCTURED FILES) OR RECORDS (STRUCTURED FILES) 

0 type IDENTIFIES THE TYPE OF POSITIONING (INPUT) 
0 -1 GO TO THE BEGINNING OF FILE (n = 0) 
0 +1 GO TO THE END OF FILE (n = 0) 

Q 0 SKIP NEW LINE CHARACTERS OR RECORDS (n positive or negative) 

0 2 POSITION TO AN ABSOLUTE CHARACTER OR RECORD (n) 

Q 3 SKIP CHARACTERS (stream input) (n positive or negative) 
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iox ENTRY POINTS 



* iox $modes 



i USED TO OBTAIN OR SET MODES THAT AFFECT THE SUBSEQUENT BEHAVIOR 
OF THE SWITCH (BEST KNOWN MODES ARE THOSE ASSOCIATED WITH tty_ : 
echoplex , tabs, polite , etc .) 



D call iox_$modes (iocb_ptr, newjnodes, old_ modes, code); 



I SWITCH MUST BE ATTACHED VIA AN I/O MODULE THAT SUPPORTS MODES 
(EXAMPLE: tty_ SUPPORTS MODES, vfile_ DOES NOT) 



0 FOR A LIST OF THE VALID MODES, SEE THE DESCRIPTION OF THE MODULE 
INVOLVED 



iox $ con tr o 1 



call iox_$control ( iocb_ptr , order, info_ptr, code); 

I info_ptr IS NULL OR POINTS TO DATA WHOSE FORM DEPENDS ON THE 
MODULE 



I PERFORMS A SPECIFIED CONTROL ORDER ON AN I/O SWITCH; THE ALLOWED 
ORDERS DEPEND ON THE I/O MODULE VIA WHICH THE SWITCH IS ATTACHED 
(REFER TO THE I/O MODULE WRITE UPS) 

0 EXAMPLES OF tty_ CONTROL ORDERS: set_delay, set_editing_ char s , 
quit_ enable, hangup 

D EXAMPLE OF vfile CONTROL ORDtR: read position (RETURNS THE 
ORDINAL POSITION - (0, 1, 2...) OF THE - NEXT RECORD/BYTE AND 
THE END OF THE FILE) 
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AN EXAMPLE USING iox 



print^file: proc; 

del iox_$attach_name entry (char (*) , ptr , char (*), ptr , fixed bin (35)); 
del iox3 detach L iocb entry (ptr, fixed bin (35)); 

del iox_$open entry (ptr, fixed bin, bit (1) unaligned, fixed bin (35)); 
del iox~$ close entry (ptr, fixed bin (35)); 

del iox_$put chars entry (ptr, ptr, fixed bin (21), fixed bin (35)); 
del iox^read* record entry (ptr, ptr, fixed bin (21), fixed bin (21), 

fixed bin (35)); 

del iox — $read_ length entry (ptr, fixed bin (21), fixed bin (35)); 
del iox - $get line entry (ptr, ptr, fixed bin (21), fixed bin (21), 

fixed bin (35)); % 
del iox_$ control entry (ptr, char (*) , ptr, fixed bin (35)); 
del iox~$user_output ext ptr; 
del iocb_ ptr ptr init (null ()); 
del code~fixed bin (35) init (0); 
del com_ err_ entry options (variable); 

del ME char (10) static init ( M pr int_ file" ) options (constant); 
del LF char (1) static options (constant) init ( " 

"); 

del 1 info, 

2 next_ position fixed bin (34), 

2 last"position fixed bin (34); 
del buffer char (buf — len) based (buf_ ptr); 
del Duf_len fixed bin (21); - 
del ouf~ptr ptr init ( nullO ); 
del rec~len fixed bin (21); 
del i fixed bin; 
del (null, addr) builtin; 
del cleanup condition; 

on cleanup call WRAPUP; 

call iox $attach name ("sw", iocb ptr, "vfile sample file", null (), code); 
if code """= 0 
then call WRAPUP; 

4 

call iox $open ( iocb ptr, 4, "0"b, code); 
if code w = 0 
then call WRAPUP; 

call iox — $control (iocb ptr, "read_position" , addr(info), code); 
if code "= 0 
then call WRAPUP; 

call iox $read_ length (iocb ptr, rec_ len , code); 
if code **"= 0 ~ 
then call WRAPUP; 

buf_ len = rec_ len + 40; 
allocate buffer set (buf_ptr); 
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AN EXAMPLE USING iox 



do i = 1 to last position; 

call iox $reaa r record ( ioo>"ptr , bufjptt , buf len , rec^£€n, c o^eT; 
if code *= 0 " — ^ " " 

then call WRAPUP; 

substr (buffer, rec__len+1 , 1 ) = LF ; 

call iox $put chars - (iox $user output, buf ptr , rec len + 1, code); 
if code *= 0 ~ 
then call WRAPUP; 
end /* do i */; 

call WRAPUP; 

WRAPUf : proc; 

if code ~= 0 

then call com_err_ (code, ME); 

if iocb^_ptr ~ = null () 
then do; 

call iox_ $close ( iocb_ptr , code); 
call iox_$detach_iocb ( iocb_ptr , code); 
end /* then do */; ~~ 

if buf_ptr ~= null () 

then free buf_ ptr -> buffer; 

goto FINIS ; 

end /» WRAPUP */; 

FINIS: 

end /* print_file */; 



r 14:40 0.259 32 

! vfs sample_file 
type: sequential 
records: 5 
r 14:41 0.261 19 

! print_file 

This Ts record number 1 
THIS IS RECORD TWO 
Hi, I'm the third record 
Would you believe four? 
I am the last record 
r 14:41 0.288 7 
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Topic IX THE IOA_ SUBROUTINE Topic IX 

OBJECTIVES: 

Upon completion of this topic* students should be able to! 

1. Write simple character strings to the user's terminal. 

2. Use iteration and conditional evaluation to form complex 
output strings for display on the terminal. 

3. Write to a file via an I/O switch. 

4. Write to a file using the Multics Virtual Memory. 
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CHARACTERISTICS 



• USED FOR FORMATTING A CHARACTER STRING FROM FIXED-POINT NUMBERS, 
FLOATING-POINT NUMBERS, CHARACTER STRINGS, BIT STRINGS, AND POINTERS 



I THE CHARACTER STRING IS FORMATTED ACCORDING TO THE CONTROL 
CHARACTERS EMBEDDED IN AN «ioa 1 CONTROL STRING 



I THE ENTIRE PROCEDURE IS SIMILAR TO FORMATTING OUTPUT IN PL/I OR 
FORTRAN 



• SEVERAL ENTRY POINTS ARE PROVIDED IN f ioa ■ TO PROVIDE VARIOUS OPTIONS 



I SINCE ALL OF THE ENTRY POINTS CAN BE CALLED WITH A VARIABLE 
NUMBER OF ARGUMENTS, THEY ALL MUST BE DECLARED 'entry 
options( variable) * 



0 ' ioa » NORMALLY APPENDS A NEW LINE CHARACTER TO THE END OF THE 
STRING CREATED 



I A CORRESPONDING ENTRY POINT IS PROVIDED FOR EVERY STANDARD ENTRY 
POINT WHICH SPECIFIES THAT "NO NEW LINE" IS TO BE APPENDED 
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ENTRY POINTS 



ENTRY POINTS IN ioa_ ARE: 

I ioa_, ioa_$nnl 

Q call ioa_ ( control^ string , arg1_, . .., arg N) ; 

I FORMAT THE INPUT DATA ACCORDING TO THE CONTROL STRING, AND 
WRITE THE RESULTING STRING ON » user_output » 

D ioa_$ ioa_stream , ioa — $ ioa^stream^nnl 

0 call ioa_$ ioa_ stream (switchname, control^ str ing , argj[, 

arg N) ; 

D FORMAT THE RESULTING STRING AS ABOVE, BUT THE STRING IS THEN 
WRITTEN TO AN I/O SWITCH SPECIFIED BY THE SWITCHNAME ARGUMENT 

I ioa_$ioa_ switch, ioa_ $ ioa_ switch_nnl 

II call ioa_ $ ioa_switch ( iocb ptr , control_str ing , argj_, 

™* arg NT; 

1 IDENTICAL TO THE ioa_$ioa stream AND ioa $ ioa_$ stream_nnl ENTRY 
POINTS EXCEPT THAT THE I/O SWITCH IS DESIGNATED BY A POINTER 
TO ITS IOCB, RATHER THAN BY SWITCHNAME (HENCE, THESE ENTRY 
POINTS ARE A BIT MORE EFFICIENT) 
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ENTRY POINTS 



0 ioa_ $rs, ioa__$rsnnl 



fl call ioa_$rs ( control_str ing , ret — string, ret — length, arg1_ 

. . . , arg N) ; 



I EDITING OCCURS AS IN THE ABOVE CALLS, BUT INSTEAD OF BEING 
WRITTEN TO AN I/O SWITCH, THE STRING IS PASSED BACK TO THE 
CALLER IN A CHARACTER STRING VARIABLE 



THE CHARACTER STRING VARIABLE PROVIDED BY THE CALLER MAY BE 
VARYING OR NONVARYING, ALIGNED OR UNALIGNED AND OF ANY LENGTH 



I THE LENGTH OF THE CREATED STRING IS ALSO RETURNED 



1 ioa__ $rsnp, ioa_$rsnpnnl 



0 THESE ARE IDENTICAL TO THE ioa_$rs AND ioa $rsnnl ENTRY POINTS 
EXCEPT THAT THEY DO "NO PADDING" OF A STRING RETURNED INTO A 
NONVARYING CHARACTER STRING 
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CONTROL STRING 



• A NON-VARYING CHARACTER STRING CONSISTING OF TEXT TO BE COPIED AND/OR 
ioa CONTROL CODES 



• ioa CONTROL CODES ARE ALWAYS IDENTIFIED BY A LEADING CIRCUMFLEX 
( *) — CHARACTER , AND SPECIFY THE TYPE OF EDITING TO BE DONE FOR THEIR 
CORRESPONDING argi 



• PROCESSING BY ioa BEGINS BY SCANNING THE CONTROL STRING UNTIL A 
CIRCUMFLEX IS FOUND, OR THE END OF THE STRING IS REACHED 



ANY TEXT (INCLUDING BLANKS) PASSED OVER IS COPIED TO THE OUTPUT 
STRING 



CONTROL CODES ARE INTERPRETED, GENERALLY BY EDITING THE NEXT 
argi INTO THE OUTPUT STRING IN A FASHION DICTATED BY THE CONTROL 
CODE 
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CONTROL STRING 



CONTROL CODE ACTION 

*d ~nd Edit a fixed-point decimal integer 

"i A ni same as ~d (FOR COMPATIBILITY WITH FORTRAN) 

*f ~nf Edit a floating-point number 
~n.df 
~7d? 

A e *ne Edit a floating-point number in exponential 

form 

" o "no Edit a fixed-point number in octal 

" w A nw Edit a full machine word in octal 

*a ~na Edit a character string in ASCII 

"b "nb Edit a bit string 
"n.db 
"Tdb 

A p Edit a pointer 

*! "ni Insert formfeed character(s) 

V A n/ Insert newline character(s) 

~n- Insert horizontal tab character(s) 

~x *nx Insert space character(s) 

~n~ Insert circumflex character(s) 

~s ~ns Skip argument(s) 

*( *n( Start an iteration loop 

*) End an iteration loop 

~ [ Start an if/then/ else or case selection group 

A ] Limit the scope of a *[ 

" ; Use as a clause delimiter between *[ *] 

~nt A n .mt Insert enough space to reach column n 
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CONTROL STRING 



• WHEN n AND/OR d APPEAR IN A CONTROL CODE, THEY GENERALLY REFER TO A 
FIELD~WIDTH Off* A REPETITION FACTOR (THE EXACT MEANING DEPENDS ON 
THE CONTROL CODE WITH WHICH THEY APPEAR) 



fl THE n OR d MUST BE SPECIFIED AS UNSIGNED DECIMAL INTEGERS, OR AS 
THE LETTER "v% IN WHICH CASE, THE NEXT argi ARGUMENT (WHICH 
MUST BE FIXED BINARY) IS USED TO OBTAIN THE ACTUAL VALUE 



• IF NO FIELD WIDTH IS SPECIFIED, ioa_ USES A FIELD LARGE ENOUGH TO 
CONTAIN THE DATA TO BE EDITED 



• IF TOO SMALL A FIELD WIDTH IS SPECIFIED, ioa IGNORES THE WIDTH AND 
SELECTS AN APPROPRIATE WIDTH 



• NUMERIC CONTROL CODES TAKE ANY PL/I NUMERIC DATA TYPE, INCLUDING A 
NUMERIC CHARACTER STRING, AND USE STANDARD PL/I CONVERSION ROUTINES 
IF NECESSARY 



• ARGUMENTS THAT ARE EDITED INTO THE CONTROL STRING MAY BE ARRAYS 



H THE ELEMENTS ARE TREATED SEPARATELY IN ROW MAJOR ORDER 
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CONTROL STRING 



• THE FOLLOWING EXAMPLES ILLUSTRATE MANY, BUT NOT ALL, OF THE FEATURES 
OF THE ioa^_ SUBROUTINE. THE SYMBOL b IS USED TO REPRESENT A SPACE 
IN THE PLACES WHERE THE SPACE IS SIGNIFICANT 

Source: call ioa_( "This is A a the third of * a" ,"Mon" , lf July" ) ; 
Result: This is Mon the third of July 

Source: call ioa_("date ~d/~d/~d, time A d:~d" ,6,20,74,2014, 36) ; 
Result: date 6/20/74, time 2014:36 

Source: call ioa_( "overflow at ~p" ,ptr); 
Result: overflow at 27114671 

Source: call ioa_( "~2 (~2 (~w *) V) " ,w1 ,w2,w3,w4) ; 

Result: 112233445566 000033004400 
000000000001 777777777777 



Source: bits "1 1 01 1 1 00001 1 "b; 

call ioa_( "*vxoct=" ,3b hex = 

Result: £Bfc££Boc t= 6 70 3 Bhex=DC 3 



.4b" ,6, bit, bit); 



Source: call ioa_("~f ~e *f "5 . 2f " , 1 . 0, 1 , 1e-1 0 , 1 ) ; 

Result: 1. £1 .eO b1.e-10 161.00 

Source: call ioa_("*(*d " , 1 , 2, 56 , 198 , 456 . 7, 3e6 ) ; 

Result: 1 2 56 1 98 456 3000000 



Source: abs sw=0; 

calT ioa_$rsnnl( "~v( Absentee user ~)~a ~a logged out.", 

out_ str , outwent ,abs_sw," Le Valley" ,"Shop") ; 

Result: out cnt=25; 

out~str="Le Valley Shop logged out." 
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CONTROL STRING 



Source: abs sw= 1; /• Using same call to ioa $rsnnl */ 

call ioa — $rsnnl( n *v( Absentee user "T"a * a logged out.", 

~ out — str ,out_cnt ,abs — sw," le Valley" ,"Shop") ; 

Result: out — cnt=39; 

out^str= "Absentee user Le Valley Shop logged out." 

Source: del a(2,2)fixed bin init( 1 ,2, 3» 4); 
call ioa_("*d~s ~d ~w",a); 

Result: 1 3 000000000004 



Source: del b(6:9)fixed bin init(6 , 7, 8, 9) ; 

call ioa - ("*v(' s 3d") n ,dim(b,1) ,b) ; 

Result: 6 7 8 9 



Source: sw="0"b; 

call ioa_ ("a=~d ~[b=~d~;~s~] c=~d" ,5,sw,7, 9) ; 

Result: a=5 c=9 



Source: sw= "1 "b; 

call ioa_ ("a=~d ~[b=~d~; ~s~] c= A d" , 5, sw, 7, 9) ; 

Result: a=5 b=7 c=9 



Source: dirs"> !f ; enames"foo"; 

call ioa__ ("Error in segment A a~[ > ~] "a" , dir, 
( dir * = ">") , ename) ; 

Result: Error in segment >foo 



Source: dir=">foo"; ename="bar"; 

call ioa_ ("Error in segment ~ a~[ > ~] ~a" , dir, 
~~ (dir * = "> w ) , ename); 

Result: Error in segment >foo>bar 



Source: option=2; /* Assume following call # is on one line */ 
call ioa — ("Insurance option selected: 
'"[no fault*; bodily injury~;propertydamage~] " , option); 

Result: Insurance option selected: bodily injury 
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CONTROL STRING 



YOU ARE NOW READY FOR WORKSHOP 
#6 
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Topic X MULTICS STORAGE SYSTEM SUBROUTINES Topic X 

OBJECTIVES: 

Upon completion of this topic* students should be able to: 

1- Add and remove entries to and from the Multics Storage 
System. 

2. Manipulate pathnames using Multics subroutines. 

3. Obtain status information on entries in the storage system. 

4. Change the access control lists (ACLs) of various entries in 
the storage system. 

5. Use Multics subroutines to obtain information about a user's 
homer working* and process directories. 

6. Discuss the access required to perform any of the above 
o perat i ons . 
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THE MULTICS STORAGE SYSTEM 



• THE STORAGE HIERARCHY IS ORGANIZED INTO AN INVERTED TREE STRUCTURE 

I THIS TREE IS MADE UP OF DIRECTORY SEGMENTS, SEGMENTS, MULTI-SEGMENT 
FILES AND LINKS 



• FOR NON-DIRECTORY SEGMENTS: 

I SUBJECT TO THE THREE ACCESS CONTROL MECHANISMS, THE USER IS FREE 
TO CREATE, DESTROY, AND MODIFY THE CONTENTS OF SEGMENTS 

I USER-CREATED SEGMENTS NORMALLY "RESIDE" IN THE RING OF THE CREATOR. 
THE USER IS FREE TO ACCESS SUCH SEGMENTS WITHOUT HAVING TO "CROSS" 
ANY RING BOUNDARIES 



• FOR DIRECTORY SEGMENTS: 

1 THE USER MAY CREATE, DESTROY, AND MODIFY DIRECTORY SEGMENTS, BUT 
NOT DIRECTLY (THEY ARE PROTECTED AGAINST DIRECT ACCESS VIA THE 
RING MECHANISM) 

0 ALLOWING USERS TO MANIPULATE DIRECTORY SEGMENTS DIRECTLY WOULD 
BE INVITING CHAOS, SINCE DIRECTORY SEGMENTS DETERMINE THE INTEGRITY, 
SECURITY AND CONSISTENCY OF THE HIERARCHY 

1 DIRECTORY SEGMENTS ARE PLACED IN RING 0 AND USERS ULTIMATELY 
ACCESS SUCH SEGMENTS BY USING A SYSTEM-PROVIDED GATE PROCEDURE 
CALLED hcs 
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THE MULTICS STORAGE SYSTEM 



* THE hcs SUBROUTINE 



I PROVIDES VARIOUS ENTRY POINTS FOR MANIPULATION OF THE STORAGE 
SYSTEM AND VIRTUAL ADDRESS SPACE 



I ALL ACCESS TO THE STORAGE SYSTEM IS ACCOMPLISHED VIA THIS GATE 
PROCEDURE 



• THE STORAGE MANIPULATION SUBROUTINES COVERED IN THIS COURSE ARE 
SUMMARIZED BELOW: 
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SUMMARY OF DISCUSSED SUBROUTINES 



CREATING STORAGE SYSTEM ENTITIES 

hes_ $ append^ branch 
hcs~$ append~branehx 
he s~$ append~lin k 
he s~$ create~branch_ 
he s_$ make_ seg 

DELETING STORAGE SYSTEM ENTITIES 

delete^ $ path 
delete_$ ptr 

OBTAINING STATUS INFORMATION 



long 
minf 
mins 

SECURITY 

get — group — id_ 

get~group~id~$ tag_star 

he s_ $ ad d_"ac 1_ en t r i e s 

he s~$ ad d_ d i r_ a c 1_ en t r i e s 

he s_ $ delete_ael_en tr ie s 

he s^$ del ete~dir_acl_en tr ies 

he s_$ f s_get_mod e 

hcs_$list_ acl 

he s~$ 1 i s t~d ir_ ac 1 

he s_$ r e pi ac e_ ac 1 

he s_ $ re pi ac e_d ir — ac 1 

WORKING, DEFAULT, AND PROCESS DIRECTORIES 

c han g e_ d e f a ul t_ wd ir_ 
change~wdir_ 
get — defaultTwdir_ 
get~pdir_ ~" 
get~wdir~ 



hcs_$ status 
hcs_$ status* 
hes_$ status* 
hes $ status' 
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SUMMARY OF DISCUSSED SUBROUTINES 



MANIPULATING PATHNAMES 

a b so 1 ut e — pa t hn am e — 

ab sol ute~ pathname^ add_suf f ix 

expand^ pathname^ ~~ 

ex pand__pathname_$ add_suf f ix 

ex pand~pathname~$com"ponent 

ex pand~pathname~$component_add_ suffix 

g et_ sho r te st_ pa th_ 

pathname^ 

pa thn am e~$ com po n en t 
pathname^ com ponent_ check 

NAMING AND MOVING DIRECTORY ENTRIES 

he s_ $ chname_ f il e 
he s_ $ chname_seg 
he s_$ f s_ mov e_ f i 1 e 
he s_ $ f s^mov e_seg 

AFFECTING LENGTH OF ENTRIES 

ad j ust_bi t_coun t_ 
he s_$ set_bc 
he sj$ truncate^ file 
t e r m in a t e_ f i 1 e"_ 

MANIPULATING THE ADDRESS AND NAME SPACES 

hes_$ fs_ get__path_name 
he s~$ fs~get~ref — name 
he s~$ fs~" get~seg~ptr 
hcs_$make_ seg ~" 
initiate 7ile_ 
term — $reTname 
term"$seg — ptr 
term~$ sing le_ref name 
term_$ term — 
term~$unsnap 
terminate file 
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CREATING STORAGE SYSTEM ENTITIES 




Requires append permission 


X 


X 


X 


X 


Can use to create segments 


X 


X 


X 


X 


Gives full access to •.SysDaemon.* 


X 


X 


X 


X 


Obeys initial ad 


X 


X 


X 


X 


Can set access for one user. id 


X 


X 


X 


X 


Can specify the user_id 






X 


X 


Can use to create directories 






X 


X 


Can set ring brackets 






X 


X 


Can set copy switch 






X 


X 


Can set bit count 






X 


X 


Can be told to chase links 








X 


Can move quota to directory 








X 


Can manipulate aim 








X 


Requires info structure 








X 


Initiates created segment 


X 









Not To Be Reproduced 



10-6 



F15C 



CREATING STORAGE SYSTEM ENTITIES 



# call hcs_ $make_seg (dir_name, entryname, ref_name, mode, 

seg_ptr , code); 



• call hcs $append branch (dir name, entryname, mode, code); 



call hcs_$append_branchx (dirjiame, entryname, mode ,' iftwlg - ^ i^U-t-d 3 

u*^»^lT*=f-Tfi.r — sw, -co py_sw , bit_count, code); 
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CREATING STORAGE SYSTEM ENTITIES 



• call hcs_ $create branch (dir name, entryname, info_ptr , code); 



I info_ptr POINTS TO THE FOLLOWING STRUCTURE: 

/» BEGIN INCLUDE FILE create_branch_info.incl.pl1 

- - - created January 1975 */ 

/* this include files gives the argument structure for 
create_branch_ */ 

del 1 create_branch_info aligned based, 
2 versTon fixed bin, 

/* set this to the largest value given below */ 
2 switches unaligned, 

3 dir sw bit (1) unaligned, 

if on, a directory branch is wanted */ 
3 copy_sw bit (1) unaligned, 

/* if on, initiating segment will be done by copying */ 
3 chase_sw bit (1) unaligned, 

/* if on, if pathname is a link, it will be chased */ 
3 pr iv_upgrade_sw bit (1) unaligned, 

/*~"pr ivileged creation (ring 1) of upgraded object */ 
3 parent ac_sw bit (1) unaligned, 

/* iT on, use parent's access class for seg or 
dir created */ 
3 mbzl bit (31) unaligned, 
/* pad to full word */ 
2 mode bit (3) unaligned, 

/* segment or directory for acl for userid */ 
2 mbz2 bit (33) unaligned, 
/* pad to full word */ 
2 rings (3) fixed bin (3 ) , 

/* branch's ring brackets */ 
2 userid char (32) , 

/* user's access control name */ 
2 bitcnt fixed bin (24) , 

/* bit count of the segment */ 
2 quota fixed bin (18), 

/* for directories, this am't of quota will be moved 
to it */ 
2 access^ class bit (72); 

/* is the access class of the body of the branch */ 

/* The following versions are implemented . . . */ 
/* (Changes to structure require defining new static 
initialized variable) */ 

del create_branch_ver sion_1 static fixed bin init (1); 

/* branch info valid through access class field */ 

/» END INCLUDE FILE create_br anchJLnfO .incl .pi 1 - - - */ 
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CREATING STORAGE SYSTEM ENTITIES 



NOTES : 

1 FOR BOTH hcs_$make_seg AND hcs_$ append^branch : 
D THE BIT COUNT AND COPY SWITCH ARE SET TO 0 
3 THE SPECIFIED MODE IS SET FOR Person_id . Pro j ect_id .* 



FOR hcs_ $make_seg , hcs_$append_branch AND hcs_$append_branchx TH 
MODE IS SPECIFIED AS FOLLOWS: ~ ~ *** 



E FOR SEGMENTS: 



read the 8-bit is 1 (01000b) 

execute the 4-bit is 1 (00100b) 
write the 2-bit is 1 (00010b) 



0 FOR DIRECTORIES: 

status the 8-bit is 1 (01000b) 

modify the 2-bit is 1 (00010b) 

append the 1-bit is 1 (00001b) 



THE MODE FOR hcs $create branch IS SPECIFIED IN SIMILAR MANNER, 
USING ONLY 3 BITls 
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CREATING STORAGE SYSTEM ENTITIES 



/* BEGIN INCLUDE FILE ... access_mode_values.incl.pl1 

Values for the "access mode" argument so often used in hardcore 

James R. Davis 26 Jan 81 MCR 4844 

Added constants for SM access 4/28/82 Jay Pattin 



del (N ACCESS 
R~ACCESS 
E~ACCESS 
W~ACCESS 
RE ACCESS 
REW ACCESS 
RW_ACCESS 

S ACCESS 
M~ACCESS 
A~ACCESS 
SA ACCESS 
SM ACCESS 
SMA ACCESS 
bit (37 internal static o 

del (N ACCESS_BIN 

r'access bin 

e~access""bin 

vTaccess'bin 

rw access bin 

re~access~bin 

rew_access_bin 

s_access_bin 
m access_bin 
a~access_bin 
sa access_bin 
sm~access_bin 
sma_access_bin 

fixed bin (5) internal 
/* END INCLUDE FILE ... acc 



in it 


' tin fin nu\ 
w UUU D ) j 


init 




ini t 


' Itn 1 n n k ^ 


in x t \ 


' nnn 1 ttvo 


init 


' it 1 1 nitKN 
k I lU DJ , 


init I 


: n iii"b) , 


init i 


: n ioi"b) , 


init 1 


v "1 00 "b) , 


init 


' It <"» 1 If V \ 

v "0 1 0"b) , 


init ( 


. "00 1 "b; , 


init 1 


' If 1 f\ *f It w \ 

. "101 "b) , 


init ! 


v i 1U DJ , 


init < 


: "i 1 1 "b> ) 


tions 


( constant) ; 


init ( 


[OOOOOb) , 


init ( 


[01000b) , 


init ( 


:00100b) , 


init ( 


;oooiob) , 


init ( 


:01010b) , 


init < 


:01100b) , 


init ( 


;oi 1 10b) , 


init ( 


:01000b) , 


init ( 


:00010b) , 


init ( 


:ooooib) , 


init ( 


:01001b) , 


init ( 


;oioiob) , 


init ( 


:oioi ib)) 



static options (constant); 
ss mode values .incl .pl1 */ 
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CREATING STORAGE SYSTEM ENTITIES 

• hcs_$append_ link 

fl call hcs_$append_ link (dir_name, entryname, path, code); 
I CREATES A LINK IN SPECIFIED DIRECTORY 

I LINK'S TARGET NEEDN'T EXIST AT CREATION TIME (CODE OF ZERO STILL 
RETURNED) 

fl APPEND PERMISSION REQUIRED ON CONTAINING DIRECTORY 
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DELETING SEGMENTS, DIRECTORIES, AND LINKS 

• delete^ 

D HAS TWO ENTRY POINTS 
I del ete_$ path 

0 GIVEN AN ENTRYNAME, DELETES SEGMENTS, MSFs , DIRECTORIES, 
AND LINKS 

I delete^ $ptr 

0 GIVEN A POINTER, DELETES SEGMENTS ONLY 

11 call delete^ $path (dir — name, entryname, switches, caller, code); 

1 call delete^ $ ptr ( seg_ptr , switches, caller, code); 

I DIRECTORY TO BE DELETED NEED NOT BE EMPTY 

1 UNSNAPS ANY LINKS THIS PROCESS HAS SNAPPED TO THE OBJECTS DELETED 

I NOTE: delete CAN'T PREVENT DISASTER WHEN ONE PROCESS DELETES 
ANOTHER'S SHADED SEGMENT 



1 THE 6 BIT INPUT VARIABLE 'switches' MAKES THIS SUBROUTINE EXTREMELY 
FLEXIBLE 

I SEE THE SUBROUTINES MANUAL FOR DETAILS OF THE 6 SWITCHES 
(force_ sw, question^ sw, directory_sw, segraent_sw, link_sw, 
chase "sw) 
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OBTAINING STATUS INFORMATION 



• THE FOLLOWING 4 ENTRY POINTS RETURN STATUS INFORMATION FOR A DIRECTORY 
ENTRY (LISTED IN ORDER OF INCREASING COMPLEXITY) 



^ hcs__$status_ mins 
hcs_ $status_ minf 
hcs_$ status^ 
*hcs $ status long 



D ALL THE ABOVE ENTRY POINTS HAVE A CURIOUS ACCESS REQUIREMENT 

I INFORMATION IS RETURNED IF CALLER HAS STATUS ON THE CONTAINING 
DIRECTORY, OR NON-NULL ACCESS ON THE ENTRY 

1 ENTRYNAMES ARE NOT RETURNED UNLESS THE CALLER HAS STATUS ACCESS 
ON THE CONTAINING DIRECTORY 



I TO THE STATUS ENTRY POINTS, DIRECTORIES AND MULTI-SEGMENT FILES 
LOOK IDENTICAL 

I THE ONLY DISTINGUISHING ATTRIBUTE IS THE BIT COUNT 
5 BIT COUNT = 0 FOR A DIRECTORY 
I BIT COUNT = NUMBER OF COMPONENTS FOR A MSF 
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OBTAINING STATUS INFORMATION 



# hcs $ status minf 



0 call hcs — $ status_minf (dir — name, entryname, chase__sw, 

type" , bit_coun t , code); 



1 RETURNS BIT COUNT AND ENTRY TYPE OF ENTRY, GIVEN A PATH 



I • TYPE OF ENTRY: 

0 MEANS link 

1 MEANS segment 

2 MEANS msf OR directory 



Q OFTEN USED WHEN TRYING TO DISTINGUISH BETWEEN DIR AND MSF 



hcs $status mins 



call hcs_ $ status^ mins ( seg_ ptr , type, bit_ couflt , code); 



1 RETURNS BIT COUNT AND ENTRY TYPE OF A SEGMENT GIVEN A POINTER TO 
THE SEGMENT 
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OBTAINING STATUS INFORMATION 



• hcs $status 



Q call hcs_$status_ (dir^name, entryname, chase_sw, status^ ptr , 

~" sta"tus_ area_ ptr , code); 



I RETURNS INFORMATION ABOUT A SEGMENT, DIR, MSF, OR LINK: 



I INFORMATION INCLUDES ENTRY TYPE, DATE TIME CONTENTS LAST 
MODIFIED, DATE TIME LAST USED, NUMBER OF RECORDS USED, USER'S 
RAW MODE, USER'S EFFECTIVE MODE AND ENTRYNAMES (NO BIT COUNT) 



0 CALLER MUST PROVIDE 



I POINTER TO CALLER-ALLOCATED INFO STRUCTURE 



I POINTER TO CALLER-DESIGNATED AREA TO CONTAIN "names" (IF NULL, 
NO NAMES RETURNED) 
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OBTAINING STATUS INFORMATION 



/* BEGIN include file status_structures.incl.pl1 */ 

/* Revised from existing include files 09/26/78. 
by C. D. Tavares */ 

/• This include file contains branch and link structures 
returned by hcs_$status_ and hcs_$ status^ long . */ 

del 1 status_branch aligned based ( status^ ptr) , 
2 short aligned, 

3 type fixed bin (2) unaligned unsigned, 

/* seg , dir, or link */ 
3 nnames fixed bin (16) unaligned unsigned, 

/* number of names */ 
3 names_ relp bit (18) unaligned, 

/* see entry_names del */ 
3 dtcm bit (36) unaligned, 

/* date/time contents last modified */ 
3 dtu bit (36) unaligned, 

/* date/ time last used */ 
3 mode bit (5) unaligned, 

/* caller* s effective access */ 
3 raw mode bit (5) unaligned, 

/"* caller's raw "rew" modes */ 
3 pad1 bit (8) unaligned, 

3 records_used fixed bin (18) unaligned unsigned, 
/* number of NONZERO pages used */ 

/* Limit of information returned by hcs_ $ status_ */ 

2 long aligned, 

3 dtd bit (36) unaligned, 

/* date/ time last dumped */ 
3 dtem bit (36) unaligned, 

/* date/time branch last modified */ 
3 Ivid bit (36) unaligned, 

/• logical volume ID */ 
3 current_length fixed bin (12) unaligned unsigned. 

/* number of last page used »/ 
3 bit count fixed bin (24) unaligned unsigned, 

/▼ reported length in bits */ 
3 pad2 bit (8 ) unaligned , 
3 copy_switch bit (1) unaligned, 

/•""copy switch */ 
3 tpd switch bit (1) unaligned, 

/* transparent to paging device switch */ 
3 mdir_ switch bit (1) unaligned, 

/*"is a master dir */ 
3 dam aged_ switch bit (1) unaligned, 

/* salvager warned of possible damage */ 
3 synchronized switch bit (1) unaligned, 

/* D" synchronized file */ 
3 pad3 bit (5) unaligned, 
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OBTAINING STATUS INFORMATION 



3 ring brackets (0:2) fixed bin (6) unaligned unsigned, 
3 uid "Bit (36) unaligned; /* unique ID */ 

del 1 status link aligned based ( status_ ptr) , 

2 type fTxed bin (2) unaligned unsigned, /* as above */ 
2 nnames fixed bin (16) unaligned unsigned, 
2 names_ relp bit (18) unaligned, 
2 dtem bit (36) unaligned, 
2 dtd bit (36) unaligned, 

2 pathname^length fixed bin (17) unaligned, 

/* see pathname */ 
2 pathname^ relp bit (18) unaligned; /* see pathname */ 

del status^entr y names ( status^ branch. nnames) 
character T32) aligned based 

(pointer ( status_ area_ptr , status_ branch. names_relp) ) , 
/* array of names returned */ 
st a tus_ pathname character ( status_link.pathname_length) 
aligned based 

(pointer ( status_area_ptr , status_ link.pathname_rel p) ) , 
/* link target path */ 
status^ area_ptr pointer, 
status^ ptr pointer; 

del (Link initial (0), 

Segment initial (1), 

uii cv, wwi j luiifiai v> c ) i ha c\j uj.ii in ifCi w ax ooaox^ 

options (constant); 
/* values for type fields declared above */ 

/* END include file status structures .incl ,pl1 */ 
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OBTAINING STATUS INFORMATION 



• hcs_$ status^ long 

Q call hcs_ $status_ long (dir_name, entryname, chase_ sw, status__ ptr , 

status_area_ ptr , code); 

1 RETURNS EVERYTHING hcs_$status_ RETURNS PLUS: 
1 DATE-TIME-LAST-DUMPED (SEGS ONLY) 

0 CURRENT LENGTH IN 1024-WORD UNITS (SEGS, MSFS) 
Q BIT COUNT (SEGS, MSFS) 

Q PHYSICAL VOLUME ID OF STORAGE DEVICE ON WHICH ENTRY CURRENTLY 
RESIDES 

1 COPY AND DAMAGED SWITCH VALUES 

SEE THE switch_on and switch_off COMMANDS (AG92) 

Q RING BRACKETS 

I SEGMENT UNIQUE ID 
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OBTAINING STATUS INFORMATION 



* OTHER ENTRY POINTS THAT RETURN STATUS TYPE INFORMATION 



I hcs_$get_ author , hcs_$get_ bc_ author 

fl hcs_$get_max_ length , hcs_ $get_ max_length_seg 



Q hcs_$get_safety_sw, he s_$ get_safety_sw_seg 



fl hes $get link target 



• TO OBTAIN STATUS INFORMATION FOR ARCHIVE COMPONENTS SEE 



I ar c hi v e_$ g e t com po n en t in f o 



fl archive $list components 



fl archive $nex t component info 



1 

COVERED IN MULTICS COURSE F15D 
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OBTAINING STATUS INFORMATION 



AN EXAMPLE 



Status: proc; 

del 1 status^ branch aligned based ( status^ ptr) , 
2 type~fixed bin (2) unaligned unsigned, 
2 nnames fixed bin (16) unaligned unsigned, 
2 names_ relp bit (18) unaligned, 
2 dtcm bit (36) unaligned, 
2 dtu bit (36) unaligned, 
2 mode bit (5) unaligned, 
2 rawjnode bit (5) unaligned, 
2 pad1 bit (8) unaligned, 

2 records_used fixed bin (18) unaligned unsigned; 
del status_entr"y — names ( status^ branch. nnames) character (32) aligned 

based (pointer ( get_ system_fr ee_area_( ) , status^ branch. names_ relp) ) ; 
del pointer builtin; 

del get — system_fr ee_area_ entryO returns( ptr) ; 
del sta"tus_ptr ptr; 
del (ioa_, 

com~err__) entry options (variable); 
del he s — $ status entry (char (*) , char (*) , fixed bin (1), ptr, 

ptr, fixed bin (35)); 

del code fixed bin (35); 
del i ; 

allocate status branch; 

call hcs_$status_ ( ">udd>MEDclass>F 15C" , "s1", 0, status_ptr , 

get_ system_fr ee area_() , code); 

if code 0 
then do; 

call com_er r_ (code, "Status"); 
return; 
end /* then do */; 

call ioa_ ("Vs1 is a *[ link" ; segment* ; directory*] with *d names:", 

status_branch.type + 1, status_branch. nnames) ; 
do i s 1 to status^ branch .nnames ; 

call ioa_(" — *a", status^ entry_names( i) ) ; 
end /* do i"*/; "~ 

end /* Status */; 
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OBTAINING STATUS INFORMATION 
AN EXAMPLE 

r 15:00 0.148 19 
! Status 

s1 is a directory with 2 names: 
Stud ent_01 
s1 

r 15:00 0.124 6 
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SECURITY 

• MULTICS HAS THREE ACCESS CONTROL MECHANISMS 
I THE ACCESS CONTROL LIST MECHANISM (ACLS) 
D THE ACCESS ISOLATION MECHANISM (AIM) 

0 THE RING MECHANISM 

• hcs AND OTHER SUBROUTINES ENABLE US TO MANIPULATE THESE MECHANISMS 
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ACCESS CONTROL LISTS 



• hcs $add acl entries 



Q call hcs_$add_ael_ entries ( dir_name ,' entryname, acl^ptr , 

acl~count, code); 



I ADDS OR CHANGES ("SETS") ACL ON A SEGMENT (rewn) 

Q CALLER MUST ALLOCATE AND FILL IN AN ARRAY OF STRUCTURES 

I "MATCHING" ACCESS NAMES ACCEPTABLE TO THE set_acl COMMAND ARE 
NOT ACCEPTABLE 

I SEE msf_manager_$acl_add FOR MULTI-SEGMENT FILES 1 



• hcs $add dir acl entries 



call he s_$ ad d_dir_acl_ entries (dir_name, entryname, acl_ptr , 

acl~count, code); 



I ADDS OR CHANGES ("SETS") ACL ON DIRECTORIES (sman) 



Q SIMILAR TO hcs $ ad d_acl_en tries EXCEPT STRUCTURE MISSING 
extended mode 



1 

COVERED IN MULTICS COURSE F15D 
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ACCESS CONTROL LISTS 



/* Begin include file — acl_structures.incl.pl1 BIM 3/82 */ 
/» format: styie3 */ 

declare acl_ptr pointer; 
declare acl~count fixed bin; 

declare 1 segment^ acl aligned based (acl_ptr), 

2 version fixed bin, 

2 count fixed bin, 

2 entries (acl_count refer ( segment^ acl .count) ) 

aligned like segment_acl_entry ; 

declare 1 segment^ acl_entry aligned based, 

2 acces"s_name character (32) unaligned, 
2 mode "" bit (36) aligned, 

2 ex tended_ mode bit (36) aligned, 
2 status^ code fixed bin (35); 

declare 1 segment^ acl_array (acl_count) aligned like 

segment_acl_entr y based (acl_ptr)-; 

declare 1 directory^ acl aligned based (acl_ptr), 
2 version"" fixed bin, 

2 count fixed bin, 

2 entries ( acl_coun t refer ( director y_acl .cour 

aligned like directory_acl_entry; 

declare 1 directory_acl_entry based, 

2 access_name character (32) unaligned, 
2 mode ~" bit (36) aligned, 

2 status^ code fixed bin (35); 

declare 1 directory_acl_array (acl_count) aligned like 

director y_acl_entry based ( acl_ptr ) ; 

declare 1 delete_ acl_entry aligned based, 

2 access^ name character (32) unaligned, 
2 status~code fixed bin (35); 

declare 1 delete_acl based (acl_ptr) aligned, 

2 version fixed bin, 

2 count fixed bin, 

2 entries (acl — count refer ( delete_acl .count) ) 

aligned like delete_acl_entry ; 

declare 1 delete_acl_array (acl_count) aligned like 

delete_acl_entry based (acl_ptr); 

declare ACL_VERSI0N_1 internal static fixed bin init (1) 

options (constant); 

/* End include file acl structures .incl ,pl1 */ 
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ACCESS CONTROL LISTS 



# hcs_$delete_acl_ entries 



D call hcs_$delete_acl_ entries (dir_ name, entryname, acl_ptr , 
~~ "~ ^ acl~coun t , code); 



I DELETES ONE OR MORE ENTRIES FROM A SPECIFIED SEGMENT T S ACL 
I USES A STRUCTURE ALLOCATED BY CALLER 

I "MATCHING" ACCESS NAMES ACCEPTABLE TO THE delete_acl COMMAND 
ARE NOT ACCEPTABLE TO hcs_ $ delete_acl_entr ies 

0 SEE msf_manager_$acl_delete FOR MULTI-SEGMENT FILES 1 



hcs $delete dir acl entries 



Q call hcs_$delete_ dir_acl_en tries (dir_name, entryname, acl_ptr , 

acl~count, code); 



I DELETES ONE OR MORE ENTRIES FROM A SPECIFIED DIRECTORY 'S ACL 
I OTHERWISE SIMILAR TO hcs $delete acl entries 



1 

COVERED IN MULTICS COURSE F15D 
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ACCESS CONTROL LISTS 



• hcs_$list_ acl 

Q call hcs_$ list_acl (dir_name., entryn ame , area_ptr, 

area_ret_ptr , acl_ptr , acT — count, code); 

I RETURNS ALL OR PART OF A SEGMENT'S ACL IN A 'segment acl' STRUCTURE 
(SAME STRUCTURE AS USED BY he s_$ add_acl_entr ies) "~ 

D THERE ARE TWO DIFFERENT WAYS TO USE THIS ENTRY POINT: 

I IF ENTIRE ACL REQUIRED: 

I SET "area_ptr" NON-NULL AND EXPECT BACK "acl_count" AND 
" area_ retjptr" 

Q SUBROUTINE ALLOCATES AN ARRAY OF STRUCTURES 

I IF JUST SOME MODE ENTRIES REQUIRED: 

I SET "area_ptr" NULL 

I USER ALLOCATES AN ARRAY OF PARTIALLY FILLED IN STRUCTURES 

1 PASS A PTR TO THIS ARRAY (acl_ptr) 

Q MODES AND CODES WILL HAVE BEEN FILLED IN UPON RETURN 

• hcs_$list_dir_ acl 

II call hcs_$ list_dir_ acl (dir_ name, entryname, area_ptr, 

area_ret_ ptr , acl_ ptr , acl__count, code) ; 

I RETURNS ALL OR PART OF A DIRECTORY'S ACL 

I SIMILAR TO hcs_$list_acl EXCEPT USES dir_acl STRUCTURE 
Not To Be Reproduced 10-26 F15C 



ACCESS CONTROL LISTS 



• hcs_$replace_ acl 

Q call he s_$ r e pi ac e_ ac 1 (dir_name, entryname, acl_ptr , acl — count, 

~" no_sysdaemon_sw, code); "" 

I REPLACES ENTIRE ACL FOR A SEGMENT WITH A USER-SUPPLIED ONE 

I USES SAME STRUCTURE AS hcs_$ add_acl_entr ies AND he s_$ list_acl 
0 CAN (OPTIONALLY) ADD "rw" FOR * .SysDaemon .* 

0 CAN BE MADE TO DELETE ENTIRE ACL (IF acl_count=0 ) 

• hcs_$replace_dir_acl 

fl call hcs - $replace_ dir_acl (dir_name, entryname, acl__ptr , 

acl~count, no_sysd aemon_sw , code); 

I REPLACES ENTIRE ACL FOR A DIRECTORY 

1 USES SAME STRUCTURE AS hcs_$ * dd_dir_acl_entr ies AND 
hcs_$list_ dir_acl 

0 CAN (OPTIONALLY) ADD "sma" FOR * .SysDaemon .* 

Q CAN BE MADE TO DELETE . ENTIRE ACL 
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ACCESS CONTROL LISTS 

• he s_$ f s_ get_mod e 

II call he s_$ f s__ g e t_mod e ( seg_ptr , mode, code); 

I RETURNS THE EFFECTIVE ACCESS MODE (rew) OF THE CALLER ON A SPECIFIED 
SEGMENT 

0 TAKES INTO ACCOUNT ACL, RING BRACKETS AND CURRENT VALIDATION 
LEVEL 

1 NOTE: SINCE A POINTER IS PASSED, SEGMENT MUST HAVE BEEN MADE 
KNOWN, WHICH IMPLIES USER HAS NON-NULL ACCESS 

• get_group_ id_ 

fl user — id = get_ group_ id_ (); 

I RETURNS IN A char(32) nonvarying Personid . Pro j ectid .tag 

4 

• get_ group_ id_ $ tag_star 

0 user_ id s get_group_ id_ $ tag_star (); 

1 RETURNS Personid .Projectid .* 
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WORKING , DEFAULT , AND PROCESS DIRECTORIES 

• change_wdir_ 

fl call chang e_wdir_ (path, code); 

I CHANGES THE WORKING DIRECTORY TO THE SPECIFIED DIRECTORY 

I REQUIRES ABSOLUTE PATHNAME 

1 COMMAND INTERFACE: cwd 

• get_ wdir_ 

0 working^ dir = get_wd ir_ (); 

1 RETURNS THE ABSOLUTE PATHNAME OF THE USER'S CURRENT WORKING 
DIRECTORY IN A char(l68) nonvarying 

0 COMMAND INTERFACE: pwd 
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WORKING, DEFAULT , AND PROCESS DIRECTORIES 

# get_pdir_ 

Q process_dir = get_pd ir_ ( ) ; 

I THIS FUNCTION RETURNS THE ABSOLUTE PATHNAME OF THE USER'S PROCESS 
DIRECTORY IN A char( 1 68 )nonv arying 

Q COMMAND INTERFACE: pd 

• get_ defaul t_wdir_ 

Q defaul t_wdir = get_def aul t_wdir_ (); 

I RETURNS THE ABSOLUTE PATHNAME OF THE CALLER'S DEFAULT WORKING 
DIRECTORY IN A chard 68) nonvarying 

0 COMMAND INTERFACE: pdwd 
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WORKING , DEFAULT , AND PROCESS DIRECTORIES 

• c hang e — de faulty wdir_ 

D call chang e^defaul t_wdir_ (path, code); 

I CHANGES THE USER'S CURRENT DEFAULT WORKING DIRECTORY TO THE 
DIRECTORY SPECIFIED 

I COMMAND INTERFACE: cdwd 
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MANIPULATING PATHNAMES 



# expand_pathname_ 

0 call expand^ pathname^ (pathname, dirname, entryname, code); 



CONVERTS A RELATIVE OR ABSOLUTE PATHNAME INTO A DIRECTORY PATHNAME 
AND AN ENTRYNAME 



I COVERED IN TOPIC 5 



expand_pathname_$add_ suffix 



call expand^ pathname^ add_suf f ix (pathname, suffix, dirname, 

entryname, code); 



i SAME &S ex pand_ pathname , BUT ALSO ADDS A SPECIFIED SUFFIX ONTO 
THE ENTRYNAME, IF THAT S*UFFIX IS NOT ALREADY PRESENT 



ex pand_ pa thn am e_ $ com po n en t 



0 call expand^ pathname^ $ component (pathname, dirname, entryname, 

componentname , code); 



I EXPANDS A ^RELATIVE OR ABSOLUTE PATHNAME INTO A DIRECTORY NAME, 
AN ARCHIVE NAME, AND AN ARCHIVE COMPONENT PORTION (OR INTO A 
DIRECTORY NAME AND ENTRYNAME PORTION IF NO COMPONENT NAME IS 
PRESENT) 
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MANIPULATING PATHNAMES 

« expand_ pathname_$component_add_ suf f ix 

fl call expand_pathname_$component_add_suf f ix (pathname, suffix, 

dirname, entryname, componentname , code); 

H SAME AS expand pathname_$ component , BUT ALSO ADDS A SPECIFIED 
SUFFIX TO EITHER THE ENTRYNAME OR THE COMPONENT NAME, IF NOT 
ALREADY PRESENT 

# absolute_pathname_ 

0 call absolute_pathname_ (pathname, f ull_ pathname , code); 

• absolute_pathname_ $ add_ suf f ix 

Q call absolute_pathname_$add_suf f ix (pathname, suffix, 

~ f ull_ pathname , code); 

1 SAME AS absolute_pathname , BUT ALSO ADDS A SPECIFIED SUFFIX IF 
THAT SUFFIX IS NOT ALREADY PRESENT 



Not To Be Reproduced 



10-33 



F15C 



MANIPULATING PATHNAMES 



• g e t_ sho r te s t_ pa t h — 

Q shortest^ path = get_shortest_ path_ ( original^ path) ; 



pathname^ 

Q path s pathname^ (dirname, entryname); 



I GIVEN A DIRECTORY NAME AND AN ENTRY NAME, RETURNS THE PATHNAME 
OF THE ENTRY IN A char (168) 

0 IF THE RESULTING PATHNAME IS >1 68 CHARACTERS, THE LAST 20 
CHARACTERS OF THE RESULT ARE SET TO "<PATHNAME TOO L0NG>" 



• pathname^ component 

Q path = pathname^ $ component (dirname, entryname, cornponen t_name) ; 



I GIVEN A DIRECTORY NAME, AN ENTRY NAME, AND OPTIONALLY, AN ARCHIVE 
COMPONENT NAME, CONSTRUCTS A PATHNAME OR AN ARCHIVE COMPONENT 
PATHNAME 

I IF COMPONENT NAME IS NULL AND THE RESULTING PATHNAME IS >1 68 
CHARACTERS, THE LAST 20 CHARACTERS OF THE PATHNAME ARE SET TO 
"<PATHriAME TOO L0N*G>" 

0 IF COMPONENT NAME IS NOT NULL AND THE RESULTING PATHNAME IS 
>1 94 CHARACTERS, THEN THE LAST 20 CHARACTERS OF THE 
dirname> entryname PORTION OF THE ARCHIVE PATHNAME ARE CHANGED 
TO "<PATHNAME TOO LONG>" AND THE comDonent_name REMAINS IN 
THE PATHNAME 
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MANIPULATING PATHNAMES 



• pathname^ com ponent_ check 



fl call pathname_$component_ check (dirnarae, entryname, 

component name, path, code); 



tt SAME AS pathname $ component EXCEPT A STATUS CODE INDICATES 
TRUNCATION INSTEA0* OF AN INVALID PATHNAME CONTAINING "<PATHNAME 
TOO LONG>" 



• NOTE: NONE OF THE PREVIOUS SUBROUTINES CHECK TO SEE IF THE ENTRY 
EXISTS 
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ANIPULATING PATHNAMES 



YOU ARE NOW READY FOR WORKSHOP 
#7 
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Topic XI MORE MULTICS STORAGE SYSTEM SUBROUTINES Topic XI 

OBJECTIVES: 

Upon completion of this topic? students should be able to: 

1. Move entries from one place in the storage system to another. 

2. Chanse the lengths and names of entries in the storage 
system. 

3. Add and remove entries to and from the user's name space. 
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NAMING AND MOVING DIRECTORY ENTRIES 



• hcs_ $chname_file 

Q call hcs_ $chname_file (dir_name, entryname, *oldname, 

newname, code); 

I ADDS, DELETES, OR CHANGES NAMES OF SEGMENTS, DIRECTORIES, MSFS, 
OR LINKS (SPECIFIED BY NAME) 

0 EITHER oldname OR newname (BUT NOT BOTH) MAY BE null ("") 

0 MODIFY PERMISSION ON CONTAINING DIRECTORY REQUIRED 

# hcs_$chname_seg 

II call hcs_$chname_ seg ( seg_ptr , oldname, newname, code); 

I ADDS, DELETES, OR CHANGES NAMES OF A SEGMENT, GIVEN A POINTER TO 
IT 

1 OTHERWISE SIMILAR TO hcs_$ chname_file 
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NAMING AND MOVING DIRECTORY ENTRIES 
he s — $ f s_ mov e_ f il e 

D call he s_$ f s__mov e_f il e ( from_dir , from — entry, at_sw, 
— to_ dTr , to_entry, code);"* 

1 MOVES CONTENTS OF ONE SEGMENT TO ANOTHER SEGMENT 

I at_sw HAS 2 BITS (fixed bin(2)) 

D THE APPEND BIT ON FORCES CREATION OF NEW SEGMENT IF IT 
DOESN'T EXIST 

I THE TRUNCATE BIT ON FORCES TRUNCATION OF NEW SEGMENT IF IT 
EXISTS 

I OLD (ZEROED OUT) SEGMENT REMAINS 
I RECORD LENGTH = 0 

I BIT COUNT NOT CHANGED 

II NEW SEGMENT'S BIT COUNT NOT ADJUSTED 

I ACCESS REQUIRED 

I READ AND WRITE ON OLD SEGMENT 

I READ, WRITE ON NEW SEGMENT (IF IT EXISTS) 

D APPEND ON NEW SEGMENT'S CONTAINING DIRECTORY (IF SEG MUST 
BE CREATED) 

0 FOR A SHORT TIME, 2 IMAGES EXIST (POSSIBLE QUOTA PROBLEM) 
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NAMING AND MOVING DIRECTORY ENTRIES 



• he s_$ f s_ mov e_seg 

fl call he s_$ f s_inov e_seg ( from_ptr , to_ptr , trun_sw, code); 

I MOVES CONTENTS OF ONE SEGMENT TO ANOTHER, GIVEN POINTERS TO EACH 
I trun_sw HAS ONLY ONE BIT 
I OTHERWISE SIMILAR TO hcs_$fs move file 
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AFFECTING THE LENGTH OF A FILE 

• hcs_ $ truncate^ file 

0 call hcs_$ truncate^ file (dir_name, entryname, length, code); 

1 TRUNCATES A SEGMENT TO A SPECIFIED LENGTH (IN WORDS), GIVEN ITS 
NAME AND CONTAINING DIRECTORY NAME 

I TRAILING FULL PAGES ARE DISCARDED 

I ZEROES ARE STORED (IN LAST PAGE) BEYOND SPECIFIED LENGTH 
I WRITE. PERMISSION ON TARGET REQUIRED 

I THE BIT COUNT IS NOT SET (USE EITHER hcs_$set_bc OR 
ad j ust_bit_coun t_ ) 

0 truncate COMMAND PERFORMS BOTH hcs_$ tr uncate_fil e AND 
hcs $set be 
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AFFECTING THE LENGTH OF A FILE 

hcs_ $ set_bc 

fl call hcs_ $set_bc (dir_name, entryname, bit_ count, code); 

1 SETS THE BIT COUNT OF A SEGMENT TO A SPECIFIED NUMBER, GIVEN ITS 
NAME AND CONTAINING DIRECTORY 

I ALSO SETS BIT COUNT AUTHOR TO USER ID OF CALLER 
I WRITE PERMISSION ON SEGMENT REQUIRED 
I MODIFY PERMISSION ON DIRECTORY NOT REQUIRED 
I COMMAND INTERFACE: set_bit_count (sbc) 

ad j ust_ bi t_ co un t_ 

fl call ad just_bit_ county (dir_ name, entryname, char_sw, 

bit~count, code); 

I SETS THE BIT COUNT TO THE LAST NON-ZERO WORD OR BYTE 
I WORKS ON SEGMENTS AND MULTISEGMENT FILES 

I char sw DETERMINES WHETHER THE BIT COUNT IS ADJUSTED TO THE 
LAST WORD OR CHARACTER 

I COMMAND INTERFACE: adjust bit count (abc) 
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AFFECTING THE LENGTH OF A FILE 

• terminate_file_ 

Q call terminate^ file_ (seg — ptr, bit_ count, switches, code); 

1 PERFORMS COMMON OPERATIONS OFTEN NECESSARY AFTER A PROGRAM HAS 
FINISHED USING A SEGMENT, SUCH AS 

I SETTING THE BIT COUNT 

I TRUNCATING THE SEGMENT 

I ENSURING THAT BITS IN THE LAST WORD OF THE SEGMENT AFTER THE 
BIT COUNT ARE ZERO 

I TERMINATING A NULL REFERENCE NAME 

I ENSURING THAT ALL MODIFIED PAGES OF THE SEGMENT ARE NO LONGER 
IN MAIN MEMORY 

I USES THE terminate file switches STRUCTURE 
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AFFECTING THE LENGTH OF A FILE 



/* BEGIN INCLUDE FILE ... terminate file .incl .p!1 
/* format: style2,*inddcls,idind32 "*/ 



*/ 



declare 1 terminate^ file__ switches 
2 truncate 
2 set_ be 
2 terminate 
2 force_ write 
2 delete 



declare 
declare 
declare 
declare 
declare 
declare 
declare 



TERM — FILE_ 
TERM_FILE_ 
TERM_FILE, 
TERM__FILE_ 
TERM_FILE_ 
TERM_FILE_ 
TERM FILE 



TRUNC 
"static 
_BC 

"static 
TRUNC_ 
"static 
TERM 
"static 
TRUNC_ 
"static 
FORCE_ 
"static 
DELETE 
"static 



options 

options 
BC 
options 

options 
BC_TERM 

options 
WRITE 

options 

options 



bit 
bit 
bit 
bit 

bit 

( constant) 
bit 

( constant) 
bit 

( constant) 
bit 

( constant) 
bit 

( constant) 
bit 

( constant) 
bit 

( constant) 



based , 
bit (1) 
(1) 
(1) 
(1) 
(1) 



unaligned , 
unaligned , 
unaligned , 
unaligned , 
unaligned; 



(1) internal 
initial ("1"b); 

(2) internal 
initial ("01"b); 

(2) internal 
initial ("11"b); 

(3) internal 
initial ( "001 "b) ; 

(3) internal 
initial ( "1 1 1 "b) ; 

(4) internal 
initial ("0001"b); 

(5) internal 
initial (»00001"b); 



/* END INCLUDE FILE 



terminate^ file .incl .pi 1 */ 



Q terminate file_ SHOULD NEVER BE CALLED FROM A CLEANUP HANDLER 
WITH THE Truncate OR set_bc SWITCHES ON (seg_ptr MAY CONTAIN AN 
INVALID SEGMENT NUMBER) 



Q force_write SHOULD BE USED ONLY WHEN DATA INTEGRITY IS ABSOLUTELY 
ESSENTIAL AS IT MAY INTRODUCE A SUBSTANTIAL REAL TIME DELAY IN 
EXECUTION 
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MANIPULATING THE ADDRESS AND NAME SPACES 

• DEFINITION OF TERMS 

I ADDRESS SPACE IS 

I THE PER-PROCESS COLLECTION OF SEGMENTS THAT CAN BE DIRECTLY 
REFERENCED VIA HARDWARE 

I EXPANDING AND CONTRACTING DURING A PROCESS 1 LIFE 

I A COLLECTION OF "KNOWN" SEGMENTS 

I REFLECTED IN THE DSEG (AND KST) 

Q MANAGED 

I AUTOMATICALLY BY THE DYNAMIC LINKER 

I IMPLICITLY, BY A CALL TO SOME SYSTEM COMMAND 

EXAMPLE: print my_dir>my_seg 

0 EXPLICITLY, BY USER CALLS TO SYSTEM COMMANDS OR SUBROUTINES 
THAT MANAGE THE ADDRESS SPACE 



Not To Be Reproduced 



11-8 



F15C 



MANIPULATING THE ADDRESS AND NAME SPACES 
D NAME SPACE IS 

I THE PER-PROCESS COLLECTION OF "REFERENCE" NAMES (OPTIONALLY) 
ASSOCIATED WITH EACH "KNOWN" SEGMENT 

I EXPANDING AND (RARELY) CONTRACTING DURING A PROCESS' LIFE 

I REFLECTED IN THE REFERENCE NAME TABLE (RNT) 

0 AN IMPORTANT PART OF SEARCH RULES (INITIATED SEGMENTS LIST) 

D MANAGED 

I AUTOMATICALLY BY THE DYNAMIC LINKER 

I EXPLICITLY, BY USER CALLS TO SYSTEM COMMANDS OR SUBROUTINES 
THAT MANAGE THE NAME SPACE 

I MAKING-KNOWN INVOLVES 

1 DEVELOPING A POINTER TO A S PE C IF IE D ^}E GM E NT (ASSIGNING A SEGMENT 
NUMBER) V 

fl ADDING AN ENTRY TO THE KST AND DSEG 

I INITIATING (A REFERENCE NAME) INVOLVES 
I EXPANDING THE PROCESS' NAME SPACE 
I ADDING AN ENTRY TO THE RNT 
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MANIPULATING THE ADDRESS AND NAME SPACES 



D TERMINATING (A REFERENCE NAME) INVOLVES 
I CONTRACTING THE PROCESS 1 NAME SPACE 
I REMOVING AN ENTRY FROM THE RNT 

I MAKING-UNKNOWN INVOLVES 

I MAKING A PREVIOUSLY VALID SEGMENT NUMBER INVALID 

I FREEING UP THAT SEGMENT NUMBER FOR FUTURE REASSIGNMENT 
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MANIPULATING THE ADDRESS AND NAME SPACES 

• NOTES 

I INITIATING A REFERENCE NAME MAY TRIGGER THE MAKING-KNOWN OF A 
SEGMENT 

I TERMINATING A REFERENCE NAME MAY TRIGGER THE MAKING-UNKNOWN OF A 
SEGMENT 

I AN UNKNOWN SEGMENT CAN NOT HAVE A REFERENCE NAME 

I A KNOWN SEGMENT MAY HAVE A NULL REFERENCE NAME . 

I PRESENCE IN THE RNT IMPLIES PRESENCE IN THE DSEG (AND KST) 



Not To Be Reproduced 



11-11 



F15C 



MANIPULATING THE ADDRESS AND NAME SPACES 

• TERMINATING SEGMENTS USING term_ 

Q term — $term__ 

Q call term_ $term_ (dir_path, entryname, code); 

I REMOVES ALL REFERENCE NAMES FROM RNT 

I REMOVES SEGMENT FROM CALLER'S ADDRESS SPACE 

I REMOVES SEGMENT FROM COMBINED LINKAGE SECTION 

I UNSNAPS LNKS IN COMBINED LINKAGE QECTION THAT CONTAIN 
REFERENCES TO THE SEGMENT 

I USER SUPPLIES dir_path AND entryname 

0 COMMAND INTERFACE: terminate ( tm) 

0 tera_$ seg__ptr 

D call term_ $ seg_ptr ( seg_ptr , code); 

1 LIKE term_$term_, BUT ACCEPTS A PTR TO SEGMENT 
I COMMAND INTERFACE: terminate_segno (tms) 

D term_ $refname 

0 call term_ $refname (ref_ name, code); 

I LIKE term_$term_, BUT ACCEPTS A REFERENCE NAME 
I COMMAND INTERFACE: terminate refname ( tmr) 
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MANIPULATING THE ADDRESS AND NAME SPACES 

0 term_ $ single^ refname 

Q call term_ $ sing le_re f name (ref_ name, code); 
I REMOVES A SINGLE REFERENCE NAME FROM RNT 

I BEHAVES LIKE term $refname (I.E. SEGMENT IS NOT MADE UNKNOWN) 
IFF REFNAME SPECIFIED WAS SEGMENT'S ONLY INITIATED REFNAME 

I COMMAND INTERFACE: terminate_single_refname (tmsr) 

Q term_$ un snap 

0 call term_$.unsnap ( seg_ptr , code); 
I UNSNAPS LINKS ONLY 

I DOESN'T TERMINATE REFERENCE NAMES OR MAKE SEGMENT UNKNOWN 
I NO COMMAND LEVEL INTERFACE 
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MANIPULATING THE ADDRESS AND NAME SPACES 



• initiate^ file_ 

0 MAKES A SEGMENT KNOWN WITH A NULL REFERENCE NAME 

1 (PREVIOUSLY DISCUSSED IN TOPIC 5) 



• terminate_file_ 

0 TERMINATES A NULL REFERENCE NAME 

1 (PREVIOUSLY DISCUSSED IN THIS TOPIC) 
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EXAMINING THE ADDRESS AND NAME SPACES 

• hcs_ $ fs_get_ pathname 

0 call hcs_$fs_get_ path_ name ( seg_ ptr , dir_name, ldn, 

entryname, code); 

1 GIVEN A POINTER TO A SEGMENT, RETURNS A PATHNAME FOR THE SEGMENT, 
WITH THE DIRECTORY AND ENTRYNAME PORTIONS SEPARATED (THE ENTRYNAME 
RETURNED IS THE PRIMARY NAME ON THE ENTRY) 

• he s__$ f s_get__ref_narae 

D call he s_$ f s_get_ref_name ( seg_ptr , count, ref_name, code); 

I RETURNS A SPECIFIED (I.E., FIRST, SECOND, ETC.) REFERENCE NAME 
OF A SPECIFIED SEGMENT, GIVEN A POINTER TO THE SEGMENT 

« 

• hcs_$ fs_get_ seg_ptr 

Q call hcs_$ fs_ get_seg_ ptr (ref_name, seg_ ptr , code); 

I GIVEN A REFERENCE NAME OF A SEGMENT , RETURNS A POINTER TO THE BASE 
OF THAT SEGMENT 
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PATHNAME , POINTER , REFERENCE NAME CONVERSION 
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PATHNAME, POINTER , REFERENCE NAME CONVERSION 



YOU ARE NOW READY FOR WORKSHOP 



Not To Be Reproduced 



11-17 
(End Of Topic) 



F15C 



TOPIC XII 
Commands and Active Functions 



Page 

Commands 12-1 

Characteristics of a Command 12-1 

Differences Between a Command and a Program 12-2 

Reporting Errors 12-3 

Command I/O 12-5 

Other Subroutines Used in Writing Commands 12-8 

An Example Of A Command 12-14 

Active Functions ..... 12-16 

Subroutines Used for Writing Active Functions 12-17 

Reporting Errors 12-19 

An Active Function Example 12-20 

Commands and Active Functions 12-22 

An Example Of a Command/ Active Function 12-23 

Other Useful Subroutines 12-26 



12-i F15C 



Topic XII 



COMMANDS AND ACTIVE FUNCTIONS 



Topic XII 



OBJECTIVES: 



Upon completion of this topic* students should be able to: 



1. Describe the differences between a command and an active 
f un c t i o n . 



Write a command which takes a varyins number of arsumentsr 
validates them* and performs some task. 



3. Write an active function which accepts a varyins number of 
arguments r validates them* and returns an appropriate value. 



4. Use Multics subroutines to report errors encountered during 
execution of a command or active function. 



5. Use Multics subroutines to acquire and release temporary 
working storage. 



6. Use the Multics clock and timer functions. 



Multics 
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COMMANDS 
CHARACTERISTICS OF A COMMAND 



• A COMMAND PROCEDURE IS AN OBJECT PROGRAM WHICH IS DESIGNED TO BE 
INVOKED FROM COMMAND LEVEL 



• A COMMAND PROCEDURE MUST OPERATE WITHIN STRICT OPERATIONAL LIMITATIONS, 
AND IT IS THESE LIMITATIONS THAT MAKE IT DIFFERENT FROM OTHER PROCEDURES 



• MANY SYSTEM SUBROUTINES CALLED BY COMMAND PROCEDURES RETURN PL/I 
POINTER VALUES, THUS FORCING THE AUTHOR TO CODE THE COMMAND PROCEDURE 
IN PL/I 
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COMMANDS 

DIFFERENCES BETWEEN A COMMAND AND A PROGRAM 



• THE DIFFERENCES WHICH EXIST BETWEEN A COMMAND PROGRAM AND A REGULAR 
PROGRAM ARE DEFINED BY THE THREE RESTRICTIONS BELOW: 



I BECAUSE THE COMMAND IS CALLED BY THE MULTICS COMMAND PROCESSOR 
(OR A USER-DESIGNED COMMAND PROCESSOR) 

D INPUT ARGUMENTS ARE LIMITED TO 'nonvarying unaligned character 
strings' 

D HENCE, A COMMAND IS RESPONSIBLE FOR CONVERTING THESE STRINGS 
TO WHATEVER DATA TYPES ARE REQUIRED 



I A COMMAND CAN RECEIVE ONLY INPUT ARGUMENTS 

I THE COMMAND CANNOT CHANGE THE VALUE OF ANY OF THESE INPUT 
ARGUMENTS 



i THE COMMAND MUST BE PREPARED TO HANDLE AN ARBITRARY NUMBER OF 
ARGUMENTS - THERE ARE NO PARAMETER DECLARATIONS ALLOWED 

I IF THE COMMAND IS PASSED TOO MANY ARGUMENTS, IT MUST COMPLAIN 
AND ABORT (CONSIDER HOW THE SYSTEM HANDLES "pwd a") 



fl OTHER RULES FOR MULTICS SYSTEM COMMANDS 
I USE com_err_ TO REPORT ERRORS 

I USE NO PL/I I/O (USE ica_, icx_, AND ccininand_quer y_) 
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COMMANDS 



REPORTING ERRORS 



• WHEN A COMMAND PROCEDURE DETECTS SOME ERROR, IT IS RESPONSIBLE FOR 
REPORTING IT TO THE USER IN A STANDARD FASHION: 



I cora_er r_ 

Q THE PRINCIPAL SUBROUTINE USED BY COMMANDS FOR PRINTING ERROR 
MESSAGES 

I IT IS GENERALLY CALLED WITH A NONZERO STATUS CODE TO REPORT 
SOMETHING UNUSUAL 



I IT MAY ALSO BE CALLED' WITH A CODE OF 0 TO REPORT AN ERROR NOT 
ASSOCIATED WITH A STATUS CODE 



I declare com_ err_ entry options( variable) ; 

call comber r_ (code, caller, control_str ing , argj_, 
~ argN): 

I control string IS AN OPTIONAL ioa SUBROUTINE CONTROL STRING 
(INPUT) 

Q arg1 , argN ARE ioa SUBROUTINE ARGUMENTS TO BE 

SUBSTITUTED INTO THE control_str ing (INPUT) 
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COMMANDS 
REPORTING ERRORS 

0 THE ERROR MESSAGE PREPARED BY com_err_ HAS THE FORM: 
3 caller: system^message user_ message 

0 FOR SYSTEM COMMANDS caller IS THE NAME OF THE PROGRAM 
DETECTING THE ERROR 

I EXAMPLE: (IF codes error table $wrong no of args AND nargs 
= 5) ----- 

D PL/I STATEMENT: 

call com_err_ (code, n sample_command" , 

"VYou furnished A d args.", nargs); 

1 RESULT: 

sample_ command : Wrong number of arguments supplied. 
You furnished 5 args. 

Q IF CODE - 0 ONLY A user message IS PRINTED 
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COMMANDS 



COMMAND I/O 

• IN WRITING COMMAND PROCEDURES NO LANGUAGE LEVEL I/O STATEMENTS ARE 
EVER USED 

• STANDARD INPUT/OUTPUT IS DONE USING THE FOLLOWING SUBROUTINES: 
5 ioa_ 

D USED FOR FORMATTING A CHARACTER STRING 
1 iox_ 

Q THE SUBROUTINE-LEVEL INTERFACE TO THE MULTICS I/O SYSTEM 

I command_query_ 

G THE STANDARD SYSTEM PROCEDURE INVOKED TO ASK THE USER A QUESTION 
AND OBTAIN AN ANSWER 



i IT PRINTS THE QUESTION ON THE USER'S TERMINAL, AND THEN READS 
THE »user_input' SWITCH TO OBTAIN THE ANSWER 

I declare command_query_ entry optionsC variable) ; 

eall comas an d_quer y_ ( ptr , answer, caller, control^ str ing , 

argl_, argN) ; 

I ptr POINTS TO THE query info STRUCTURE DESCRIBED ON THE 
FOLLOWING PAGE (INPUT) 
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COMMANDS 



COMMAND I/O 



/* BEGIN INCLUDE FILE query_info.incl.pl1 TAC June 1, 1973 */ 
/* Renamed to query info .incl .pl1 

ancT cp escape control added, 08/10/78 WOS */ 
/* version number changed to 47 08/10/78 WOS */ 
/* Version 5 adds explanation_( ptr len) 05/08/81 S. Herbst */ 
/* Version 6 adds literal_sw, prompt_after explanation switch 

12715/82 S. Herbst */ 

del 1 query_ info aligned, 

/* "argument structure for command_query_ call */ 
2 version fixed bin, 

/* version of this structure - must be set, see below */ 
2 switches aligned, 

/* various bit switch values */ 
3 yes or_ no_ sw bit (1) unaligned init ("0"b), 

/* not a yes-or-no question, by default */ 
3 suppress^ name_sw bit (1) unaligned init ("0"b), 

/* do not suppress command name */ 
3 cp_escape_control bit (2) unaligned init ("00"b), 
7* obey static default value */ 

/* "01" -> invalid, "10" -> don't allow, "11" -> allow */ 
3 suppress_spacing bit (1) unaligned init ("0"b), - 

/* whether to print extra spacing */ 
3 literal_sw bit (1) unaligned init ("0"b) , 

/* 0N~=> do not strip leading/ trailing white space */ 
3 prompt af ter_ex planation bit (1) unaligned init ("0"b), 

/* 0"R => repeat question after explanation */ 
3 padd'ing bit (29) unaligned init (""b), 
/* pads it out to t word */ 
2 status_code fixed bin (35) init (0), 

/* query not prompted by any error, ay default */ 
2 quer y — code fixed bin (35) init (0), 
/* "currently has no meaning */ 

/* Limit of data defined for version 2 */ 

2 question^ iocbp ptr init (null ()), 

/* 10 "switch to write question */ 
2 answer^ iocbp ptr init (null ()), 

/* 10 switch to read answer */ 
2 repeat_ time fixed bin (71) init (0), 

/* repeat question every N seconds if no answer */ 

/- minimum of 30 seconds required for repeat */ 

/* otherwise, no repeat will occur */ 

/* Limit of data , defined for version 4 */ 

2 ex planation_ptr ptr init (null ()), 

/* explanation of question to be printed if */ 

2 ex planation_len fixed bin (21) init (0); 

/* user answers "?" (disabled if ptr=null or len=0) */ 
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COMMANDS 
COMMAND I/O 



del query_ info_ version^ 3 fixed bin int static 

options (constant) init (3) 
del quer y_info_ver sion_4 fixed bin int static 

options (constant) init (4) 
del quer y_info_ver sion_5 fixed bin int static 

options (constant) init (5) 
del query_ info_ ver sion_ 6 fixed bin int static 

options (constant) init (6) 
/* the current version number */ 

/* END INCLUDE FILE query_info.incl.pl1 */ 
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COMMANDS 

OTHER SUBROUTINES USED IN WRITING COMMANDS 

cu_ 

0 USED TO MANIPULATE THE COMMAND ENVIRONMENT IN FUNCTIONS LIKE: 
I SETTING THE READY MESSAGE 
I CALLING THE COMMAND PROCESSOR 
I CHANGING THE COMMAND PROCESSOR 
I EXAMINING STACK FRAMES 



Not To Be Reproduced 



12-8 



F15C 



COMMANDS 

OTHER SUBROUTINES USED IN WRITING COMMANDS 

THE FOLLOWING ENTRIES ARE USED TO OBTAIN THE ARGUMENTS PASSED TO 
THE COMMAND 

I cu_$ arg_ count 

D call cu — $arg_ count (arg_count, code); ' 

I USED TO DETERMINE THE NUMBER OF ARGUMENTS SUPPLIED WHEN THE 
PROCEDURE WAS CALLED 

I cu_$ arg__ptr 

0 call cu_$arg_ptr ( arg_no , arg_ptr , arg_len , code); 

1 RETURNS A POINTER TO AND THE LENGTH OF ONE OF THE ARGUMENTS 

I arg_no IS AN INTEGER SPECIFYING THE NUMBER OF THE DESIRED 
ARGUMENT (INPUT) 

0 NOTE THAT A BASED VARIABLE IS NORMALLY USED FOR INPUT ARGUMENTS 
AND IS DECLARED AS FOLLOWS: 

I declare argument char( arg_len) based ( arg_ptr) ; 
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COMMANDS 

OTHER SUBROUTINES USED IN WRITING COMMANDS 



• EXAMPLES 



sample^ command : proc; 

del eu_$arg_ count entry( fixed bin, fixed bin(35)); * 
del nargs fixed bin; 

del error_ table_$wrong no_of_args fixed bin(35) external; 
del com_ err_ entry optTons( variable) ; 
del code fixed bin(35); 
• • • 

call cu_$ arg_ count (nargs, code); 
if nargs ~s 0 
then do; 

call com_err_( error_table_$wrong_no_of_arg s , 
" sam pi e_ command") ; ~" 

return ; 
end /* then do */; 



sample_command2 : proc; 

del cu_$arg_ptr entry (fixed bin ,ptr , fixed bin(21 ) ,f ixed bin(35)); 

del argument char(arg len) based ( arg_ptr) ; 

del arg_len fixed binT21); 

del arg_ptr ptr: 

del code fixed bin(35); 

del (com_err_, ioa_ ) entry options( variable) ; 

• • • 

call cu $arg ptr (1, arg ptr, arg len, code); 
if code"**= 0~ 
then do; 

call com_err_ (code, " sample^ command2") ; 
return; ~ 
end /* then do */; 
call ioa_( "First argument is ^ a" , argument) ; 

• • • 
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COMMANDS 

OTHER SUBROUTINES USED IN WRITING COMMANDS 

• THE FOLLOWING SUBROUTINES ARE USED FOR ARGUMENT CONVERSION: 

I expand_pathname_ 

0 call expand_ pathname^ (pathname, dirname, entryname, code); 

1 PREVIOUSLY DISCUSSED IN TOPICS 5 AND 10 

I NOTE THAT SOME CRITICAL MULTICS SUBROUTINES REQUIRE A PATHNAME 
ARGUMENT SPECIFIED IN TWO PORTIONS, THE DIRECTORY PATHNAME 
AND THE ENTRYNAME, AND THIS IS ONE OF THE MAIN REASONS 
expand_pathname_ IS AVAILABLE 

I cv__ptr_ 

0 ptr_value = cv_ptr_ (vptr, code); 

1 THIS FUNCTION CONVERTS A VIRTUAL POINTER TO A POINTER VALUE 
(A VIRTUAL POINTER IS A CHARACTER-STRING REPRESENTATION OF A 
POINTER VALUE, SUCH AS "foo$bar" OR "> udd>PRO J>PERS>seg ! 1 200 ") 
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COMMANDS 

OTHER SUBROUTINES USED IN WRITING COMMANDS 



Q OTHER CONVERSION SUBROUTINES AND FUNCTIONS 

fl cv_bin_ 

fl cv_bin_$dec 
0 cv_ bin_ $oct 

0 cv_dec_, cv_ dec_ check_ 

0 cv_oct_, cv_oc t_ check_ 

Q cv_hex_, cv_hex_check_ 

0 cv_float_ 

C c v_ fl o a t_do ub 1 e_ 

0 cv_ptr_$ terminate 

fl ev_entry_ 

Q cv_mod e__ 

0 cv_ dir_ mode_ 

0 cv_userid_ 

0 cv_ error_ 

fl cv error $name 
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COMMANDS 

OTHER SUBROUTINES USED IN WRITING COMMANDS 



This Page Intentionally left Blank 
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COMMANDS 
AN EXAMPLE OF A COMMAND 



how_long: proe; 

del cu_ $arg_count entry (fixed bin, fixed bin (35)); 

del ciT$ arg~ptr entry (fixed bin, ptr , fixed bin(21), fixed bin (35)); 

del expand_ pathname^ entry (char (*), char (*) , char (*) , fixed bin (35)); 
del hes $status min"f entry (char(*), char(*), fixed bind), fixed bin(2 ) , 

fixed bin(24), fixed bin(35)); 
del long bit (1) init ( w 0"b); 

del arg char (argl) based (argp); 

del (i, nargs) fixed bin; 

del argl fixed bin(21); 

del argp ptr; 
del type fixed bin (2); 

del code fixed bin (35); 

del dir char (168); 

del entry char (32); 

del ( com_er r_, 

ioa_) "" entry options (variable); 

del ME char (8) static init ( "how_long") options (constant); 

del be fixed bin (24); 

del null builtin; 

del error^table^wrong^no^ of^args fixed bin(35) external; 
/* check number of args */ 



call cu_$arg_ count (nargs, code); 
if (nargs < T) ! (nargs > 2) 
then do; 

call c om_ err ( er ror__tabl e_$wrong__no__of__arg s , ME); 
return ; "~ 
end /* then do */; 



/* evaluate args */ 



do i 4 s 1 to nargs; 

call cu__ $arg_ ptr (i, argp, argl, code); 

if i = 1 
then do; 

call expand_pathname_ (arg, dir, entry, code); 
if code "= 0" 
then do; 

call ccm__er r__ (code, ME); 

return; — 
end /* then do */; 
call hes $status minf (dir, entry, 1, type, be, code); 
if code "*"= 0 
then do; 

call com_err — (code, ME); 
return; 
end /* then do */; 
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COMMANDS 
AN EXAMPLE OF A COMMAND 



be = bc/36; 
end /* then do */; 
else do; 

/* second arg must be -long or -lg */ 
if (arg = "-long") { (arg = "-lg") 
then long s "1"b; 
else do; 

call com_ err_ (0, ME, "Control arg must be -long or -lg" 

return ; 
end /* else do */; 
end /* else do */; 
end /* do i */; 

call ioa_( "^[Number of words for ~a>~a is ";"2s"]"i", long, dir, entry, be) 
end /* how long */; 



r 14:03 0.197 18 
1 ho w_ long 

how~long: Wrong number of arguments supplied, 
r 14:04 0.183 11 

! how long how long 
oou 

r 14:04 0.105 0 

! how_long how_ long.pll -lg 

Number of words for >user_dir_dir>MED>Jackson>15c>how_long .pl1 is 544 
r 14:04 0.088 0 

! how^long how^long.pll -short 

how~"iong: Control arg must be -long or -lg 
r 1^:04 0.143 1 
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ACTIVE FUNCTIONS 



AN ACTIVE FUNCTION RETURNS A CHAR VARYING VALUE TO THE COMMAND 
PROCESSOR FOR SUBSTITUTION INTO THE COMMAND LINE 



II IT IS CALLED BY THE COMMAND PROCESSOR FOR THE PURPOSE OF RETURNING 
A VALUE TO THE COMMAND PROCESSOR 



I THE COMMAND PROCESSOR MUST PREPARE A LOCATION FOR THE RETURNED 
VALUE 



I THE ACTIVE FUNCTION MUST KNOW THIS LOCATION IN ORDER TO RETURN A 
VALUE 



• AN ACTIVE FUNCTION DIFFERS FROM A STANDARD PROCEDURE IN THE THREE 
WAYS SPECIFIED FOR COMMANDS (TAKES ONLY CHARACTER-STRING ARGUMENTS, 
HANDLES ONLY INPUT ARGUMENTS, TAKES A VARYING NUMBER OF ARGUMENTS) 
AND HAS ONE ADDITIONAL DIFFERENCE: 



AN ACTIVE FUNCTION MUST RETURN A VARYING CHARACTER-STRING ARGUMENT 
TO THE COMMAND PROCESSOR IN- A LOCATION SPECIFIED BY THE COMMAND 
PROCESSOR 



• A COMMAND PROCEDURE CAN BE WRITTEN TO IMPLEMENT EITHER A COMMAND OR 
AN ACTIVE FUNCTION 



• SUCH A PROCEDURE'S EXECUTION DEPENDS ON THE MANNER IN WHICH IT WAS 
INVOKED 
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ACTIVE FUNCTIONS 
SUBROUTINES USED FOR WRITING ACTIVE FUNCTIONS 

• THE SUBROUTINES USED FOR WRITING AN ACTIVE FUNCTION MUST BE ABLE TO 
DETERMINE TWO VERY IMPORTANT THINGS: 

D THE LOCATION INTO WHICH IT SHOULD PLACE ITS RETURN VALUE 
I WHETHER OR NOT IT WAS INVOKED AS A ACTIVE FUNCTION 

• cu_$af_arg_count 

0 call cu_$ af_arg_count (nargs, code); 

1 RETURNS THE NUMBER OF INPUT ARGUMENTS 

1 IF THE CALLER WAS NOT INVOKED AS AN ACTIVE FUNCTION, A NON-ZERO 
STATUS CODE IS RETURNED ( error_table_$ not_act_fcn) 

• cu_$af_arg_ptr 

Q call cu_$ af_arg_ptr ( arg_no , arg_ptr , arg__len , code); 

I OPERATES LIKE cu_$arg_ptr EXCEPT THAT IT RETURNS A NULL arg ptr 
IF IT WAS NOT CALLED AS AN ACTIVE FUNCTION 

I USUALLY USED IN WRITING PROGRAMS THAT CAN ONLY BE CALLED AS 
ACTIVE FUNCTIONS 
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ACTIVE FUNCTIONS 
SUBROUTINES USED FOR WRITING ACTIVE FUNCTIONS 



• cu_$af_ return_ arg 



0 call cu_$af_retum_arg (nargs, rtn_string_ptr , max_ length, 

code) ; 



I PERFORMS THE JOB OF cu$ af_arg_count AND 



0 MAKES THE ACTIVE FUNCTION'S RETURN ARGUMENT AVAILABLE 



I v^tn strin^ptp IS A POINTER TO THE VARYING STRING RETURN ARGUMENT 
Ot < fmri[GTLW FUNCTION (OUTPUT) 




0 \max lengthJIS THE MAXIMUM LENGTH OF THE VARYING STRING POINTED 



unax lengtryia inc. naainufi Ltm 
TO lY -r-ffrstring ptr (OUTPUT) 



0 IF THE CALLER WAS NOT INVOKED AS AN ACTIVE FUNCTION, A NON-ZERO 
STATUS CODE IS RETURNED (error table $not act fen) 



NOTE THAT THE ACTIVE FUNCTION DECLARES ITS RETURN ARGUMENT AS 
FOLLOWS: 

declare r etur n_str ing char ( max_length) varying 

based ( rtn_str ing_ptr) ; 
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ACTIVE FUNCTIONS 



REPORTING ERRORS 



• AN ACTIVE FUNCTION USES A DIFFERENT SUBROUTINE FOR REPORTING ERRORS 
TO THE USER: 



I active fnc err 



Q CALLED BY AN ACTIVE FUNCTION WHEN IT DETECTS AN ERROR 



I FORMATS AN ERROR MESSAGE MUCH LIKE cora_err_ AND THEN SIGNALS 
THE ^ctive^function^error 1 CONDITION 

I USAGE 

I declare active_fnc_err_ entry optionsC variable) ; 

I call active_fnc_err_ (code, caller, control_string , argl^, 

. . . , arg N) ; 

I THE USAGE IS SIMILAR IN ALL RESPECTS TO com err 
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.CTIVE FUNCTIONS 



AN ACTIVE FUNCTION EXAMPLE 



me: proc; 

del cu_$af_return_ arg entry (fixed bin, ptr , fixed bin(21), fixed bin (35)); 

del nargs fixed bin; 

del return^ arg char (rslength) varying based (rsptr); 

del rsleng"th fixed bin (21); 

del rsptr ptr ; 

del code fixed bin (35); 

del user_ info_ entry (char (*), char (*) , char (*)); 
del ( active_fnc_ err_ , 

com_err_) entry options (variable); 
del error_table_ $wrong_ no_ of_args fixed bin (35) external; 

del perso!T__id cha7 (22); 

del projeet_id char (9); 

del acct char (32); 

/» DETERMINE IF INVOKED AS ACTIVE FUNCTION */ 

call cu_$ af_return_arg (nargs, rsptr, rslength, code); 
if code ~= 0 
then do; 

call eom_err_ (code, "me"); 
return; 
end /* then do */; 

if nargs ~= 0 
then do; 

call ac tiv e_fnc__err__( error__table_$wrong_no_of_arg s , "me" ) ; 
return; 
end /* then do */; 

/» SO FAR, SO GOOD - GET PERS0N_ID */ 

call user_info — (person^id, projected, acct); 
return^ arg = per son_id 

end /* me */; 
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ACTIVE FUNCTIONS 
AN ACTIVE FUNCTION EXAMPLE 



r 15:19 0.143 0 
! me 

me: This active function cannot be invoked as a command, 
r 15:19 0.197 5 

! who [me] 
Jackson .MED 

r 15:20 0.524 5 

! who [me Jackson] 

me: Wrong number of arguments supplied. 

Error: Bad call to active function me 
r 15:20 0.206 9 level 2 
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COMMANDS AND ACTIVE FUNCTIONS 



• THE SUBROUTINES DISCUSSED PREVIOUSLY ARE USED IN WRITING PROCEDURES 
THAT MAY BE CALLED AS BOTH COMMANDS AND ACTIVE FUNCTIONS 



• THE FOLLOWING SUMMARIZES THE IDIOSYNCRASIES TO BE CONSIDERED IN 
CHOOSING APPROPRIATE SUBROUTINES 



cu ENTRY 



COMMAND 



ACT. 
FUNC 



COMMENTS 



arg_coun t 



IF INVOKED AS AN ACTIVE FUNCTION 
COUNT INCLUDES RETURN ARGUMENT 



arg_ptr 



af arg count 



COUNT EQUALS INPUT ARGUMENTS ONLY 



af_arg_ptr 



NULL arg_ptr IF INVOKED AS A COMMAND 



af_return_arg 



COUNT EQUALS INPUT ARGUMENTS ONLY 
NULL rtn_ptr IF INVOKED AS A COMMAND 



• IT IS ALWAYS POSSIBLE TO WRITE ANY COMMAND OR ACTIVE FUNCTION USING 
ONLY THE TWO ENTRY POINTS, cu_$ af_return arg AND cu_$arg_ptr 
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COMMANDS AND ACTIVE FUNCTIONS 



AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 



how_long_ both : proc; 

del ex pand_pathname_ entry (char (*) , char (*), char (*), fixed bin (35)); 
del cu_$arg_ptr entry (fixed bin, ptr , fixed bin(21), fixed bin(35)); 
del eu~$af_ return_arg entry( fixed bin, ptr, fixed bin(21), fixed bin (35)] 
del active~fnc_err_ entry options (variable); 

del ncs $ status minf entry ( char( *) , char(*) , fixed bind), fixed bin(2), 

fixed bin(24), fixed bin(35)); 
del long bit (1) init ("0"b); 
del arg char (argl) based (argp); 
del complain entry variable options (variable); 
del af bit (1) init ( t, 0"b); 

del return_ string char (rslength) var based (rsptr); 

del rslength fixed bin (21); 

del rsptr ptr; 

del (i, nargs) fixed bin; 

del argl fixed bin (21); 

del argp ptr ; 

del type fixed bin (2); 

del code fixed bin (35); 

del dir char (168); 

del entry char (32); - 

del ( com_ err — , ioa_ ) entry options (variable); 

del MEchar""(13) static init ( "how_long_both H ) options (constant); 
del be fixed bin (24); 

del error_ table_$wrong_no_ of_args fixed bin(35) external; 
/* check number of args */ 

call cu_$af_return_ arg (nargs, rsptr, rslength, code); 

/* command or active function invocation??? */ 

if code = 0 
then do; 

af = "1"b; 

complain = active_fnc_ err_; 
end /* then do */; ~~ 
else complain = com_ err_; 

if (nargs < 1) i (nargs > 2) 
then do; 

call complain ( error_table_$wrong_no_of_args, ME); 
return; ™ 
end /* then do */; 

/* evaluate args */ 

do i s 1 to nargs; 

call cu_$arg_ptr (i, argp, argl, code); 



Not To Be Reproduced 



12-2 3 



F15C 



COMMANDS AND ACTIVE FUNCTIONS 



AN EXAMPLE OF A COMMAND /ACTIVE FUNCTION 



/* relative pathname argument */ 

if i s 1 
then do; 

call expand pathname^ (arg, dir, entry, code); 
if code 0 
then do; 

call complain (code, ME); 
return; 
end /* then do */; 

call hcs $status_minf (dir, entry, 1, type, be, code); 
if code "*= 0 
then do; 

call complain (code, ME); 
return ; 
end /* the do */; 
be = bc/36; 
end /* then do */; 
else do; 

/* second arg must be -long or -lg */ 

if (arg = "-long") i (arg = "-lg") 
then long = "1"b; 
else do; 

call complain (0, ME, "Control arg must be -long or -lg"); 
return ; 
end /* else do */; 
end /* else do */; 

end /* do i */; 

if af 
then do; 

return_string - be; 
return" 
end /* then do */; 

call ioa_( ""[Number of words for " a> "a is " ; *2s A ] A i" , long, dir, entry, be); 
end /* how long both */; 
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COMMANDS AND ACTIVE FUNCTIONS 



AN EXAMPLE OF A COMMAND/ACTIVE FUNCTION 



r 15:59 0.284 7 

! how_long_both 
how~long~both : Wrong number of arguments supplied, 
r 15:59 0.152 11 

! how_long_both foo -Ig 

how long_both : Entry not found, 
r 1o":00 0.118 0 

! how_long both how_long both 
776 

r 16:00 0.076 0 

! how_long_both how_long_both -long 

Number of words for > user_dir_dir>MED>Jackson> f 15c> how__long_both is 776 
r 16:01 0.098 0 

! octal [how long_both how_long_both] 

1410 

r 16:01 0.196 6 

! octal C how_long_both] 

how_long_both : Wrong number of arguments supplied. 

r 16:01 0.169 7 level 2 
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OTHER USEFUL SUBROUTINES 



user info 



RETURNS INFORMATION CONCERNING A USER'S LOGIN SESSION (ALL ARGUMENTS 
ARE OUTPUT ARGUMENTS) 

fl call user_info_ (person_id, projected, acct) ; 



I OTHER ENTRY POINTS: 

I call user_ in fo_$ab sen tee_ queue (queue); 

I call user_info_$absentee_request_id ( requested ) ; 

II call user_in fo__$ ab sin (path); 

I call user_in f o_ $ ab so ut (path); 

I call user_info_$ attributes (attr); 

1 call user_info_$homedir (hdir); 

1 call us er_ in fo_$ limits (mlira, clim, cdate, erf, shlim, msp, 

csp, shsp) ; 

I call user_info $ load_ctl_info (group, stby, pr eempt_tirae , 

weight); 

1 call user_ in fo_$ log in_arg_ count (count, max_ length, 

to tal_ length) ; 

I call user_info_$login_arg_ptr ( arg_no , arg_ptr , arg_len , 

code); 
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OTHER USEFUL SUBROUTINES 



fl call uservinfo_$ login_ data (person_id, project_id, acct, 

anon, "stby, weight, time_login, 
login_word); 

I call user_ info_ $ logout_data ( logout^ channel , logout_pid); 

I call user_info_$outer_module (om); 

I call user_info_$process_type ( process^ type) ; 

I call user_info_$responder (resp); 

I call user_info_$rs_name ( rs_name) ; 

I call user_info_$ rs_ number (rs_number); 

I call user_info_ $ service_type (type); 

I call tisercin fo__$ terminal_data (id_code, type, channel, 

iine_type, charge_type) ; 

5 call user_info_$ usage_data (nproc, old_cpu, time_login, 

~ time_create , old_mem, 

old_To_cps) ; 

i call user_info_$whoami (person_id, project_id, acct); 



Not To Be Reproduced 



12-27 



F15C 



OTHER USEFUL SUBROUTINES 



• v al ue_ 

0 READS AND MAINTAINS VALUE SEGMENTS CONTAINING NAME-VALUE PAIRS 
ACROSS PROCESS BOUNDARIES 

1 CREATING A VALUE SEGMENT 

I CREATE A SEGMENT WITH A SUFFIX OF .value 

Q call value_ $ init_seg ( seg_ptr , seg type, r emote_ar ea_ptr , 

seg_si ze , cocTe) ; 

I DEFAULT VALUE SEGMENT IS [home_dir]>[user_name] .value 

0 call val ue_ $ set_path (path, create_sw, code); 

1 call value_ $get_path (path, code); 

I CREATING AND MAINTAINING NAME-VALUE PAIRS 

I call v al ue_$ set ( seg_ptr , switches, name, new_value, 
~" o 1 d__ v al ue , code); 

I call value_ $ test_ and_set ( seg — ptr , switches, name, new_value, 

old~value, code); 

I call value_$get ( seg_ptr , switches, name, value_arg, code); 

1 call value_ $list (set^tr, switches , match info_ptr , area_ptr , 

value list info ptr , cocTe) ; 

I call value_$ defined ( seg_ptr , switches, name, code); 

i call value_ $delete ( seg_ptr , switches, name, code); 
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OTHER USEFUL SUBROUTINES 



YOU ARE NOW READY FOR WORKSHOP 
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WORKSHOP ONE 



Controlled Variables and ' isub' Defining 



1 . Write a procedure called 'allocate array. p ll \ that will ask the 
user for the size of one dimensional fixed bin (17) arrays he/she 
wishes to allocate. For example, if the user provides the number 
7, your program is to allocate an array with, 7 f ixed b jji_ ( 1 7) 
elements. ~~ —— 



The program should loop f repeatedly asking for the size o f thq 
next array , .allocating that array and then initializing all eleme nts.- 
of that array to the current allocation " lev el CiTeTi the first 
array would be initialized to 1 , the second array would be initialized 
to 2, etc.). Use the 1 alloc at - i^n T h " i1h ' n tr > determine the depth. 

The program should continue allocating and initializing until the 
user responds with zero (0 ) Again using the 'allocation* builtin 
to determine the allocation depth, it should then free all the 
allocated arrays , printing each array just before freeing it . 

Test your program asking for arrays of size 1, 2, 3, and 4. 
Observe the order in which the arrays are freed. 
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2. The segment >udd>MEDclass>F15C>s1>printit .fortran contains a fortran 
subroutine that accepts a 2 by 3 array as an argument and prints 
it out a row at a time. 

Copy the segment, print it, compile it and write a PL/I procedure 
called 1 call_fortran .pl1 1 declaring a 2 by 3 array and the 3 by 2 
transpose of~"this array (use isubs) . The program should: 

a. Initialize the 2 by 3 array as follows: 

1 2 3 

4 5 6 

b. Call the fortran subroutine, passing to it the 
untransposed array. 

c. Call the fortran subroutine, passing to it the 
transposed array. 

Note : 

1) ' printit' must be declared an entry , and since it will be 
passed both a 2 by 3 and a 3 by 2 array, its descriptor must use the 
star convention (dim( *,*)). 

2) The eAeniejxts- of the array should be declared fixe d bin (35) 
since that is the d at a type for fortran integers"; 

3) The final compilation of the PL/I program will still have a 
"by value" warning since ' isub* defined variables are always passed by 
value. Recall this means that the called procedure will not be able 
to change the variable passed to it. How can this warning be avoided? 
That is, how could the array be passed by reference? 

4) When you compile the PL/I program with the table option (the 
default) , you will receive a warning that the transposed array will 
not appear in the symbol table. 
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WORKSHOP TWO 



Based Variables and Areas 



This workshop has three parts. Be sure you understand the mechanism 
used in parts 1 and 2 (based variables) , since they form the basis for 
workshop three and the remainder of this course. 



1. The following declarations are in the segment 
>udd>MEDclass>F15C>s1>include>w2.incl .pl1 . 

/* Begin w2.incl.pl1 */ 

del string char (10) varying; 

del .1 str ing_par ts based (addr (string)), 

2 length fixed bin (35), 

2 characters char (10); 

del number float binary; 

del 1 float_num based (addr (number)), 

2 sign bit (1 ) unal , 

2 exponent bit (7) unal, 

2 m_sign bit (1) unal, 

2 mantissa bit (27) unal; 

/* End w2.inci.pl1 */ 

Write a short program that^ enters data into the two BASE va r iables 
Xstring and number ) and then" — pr in ts 'out tKe values in the~~BASED 
(overlay) variables in order to see exactly how 'char vary ing' and 
' float binary * numbers are stored. (Use put data. ) 

2. Change your working directory to >udd>MEDclass>F 15C>s1 . Print the 
segment get_ message .pl1 . Execute the corresponding object segment 
and follow the directions given in the message. 

3. In your working directory create an area named AREA (all caps) 
using the create area command. In the segment, 
>udd>MEDclass>F 15C>s1 >Fill_area ,pl1 , i-s a program that allocates 2 
numbers in that area. Print the program and make sure you understand 
what it is doing. Execute the object segment. Use the dump_ segment 
(ds) command to look at your AREA segment. Notice how the pointer 
values printed by the program correspond to locations in the segment. 
Also notice the extra area manager information in the segment. 
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WORKSHOP THREE 



Gaining Direct Access to a Segment 



The segment, >ud d>MEDclass>F 15C> si >in voices . contains invoices for a 
number of different vendors. .At the base of the segment is a header. 
The remainder of the segment is a series of linked structures, each 
one representing a single invoice for a particular vendor . The declaration 
to be used for the linked structure is: 

del 1 invoice based ( p) , 

" 2 next bit (18) , 

2 invoice_ number dec (3), 
2 vendor^ number dec (3), 
2 charge"" fixed dec (8,2); 

The structure member, invoice .next , is a non-standard offset (word 
offset from the base of the segment) indicating the location of the 
next structure in the linked list. 



Write a program called ^get_invoices .pll^ /. Your program should prompt 
the user for a vendor numoer (3 Qigi'EsI and then print out all invoice 
numbers and the corresponding cnarges belonging to that vendor. 



Actually, the segment does not contain just one linked list. There 
are, in fact, 10 linked lists below the header. The header is used to 
determine which list is to be searched for that particular vendor. 
The declaration to be used for the header is: 



d el 1 invoice_file header based (seg_ptr) 
2 number^ ofjinvoices fixed bin,"" 
2 hash table (0:9) bit (18) unal; 



The hash table is made up of 10 non-standard offsets. Each offset 
points to the start of one of the linked lists of invoice structures. 
Which linked list a particular vendor is found in is determined by the 
last digit in the vendor number. For example, invoices for vendor 351 
would be in the list pointed to by * hash_table(7 ) ' ■ — ■ — — 3 



Th u s , when a user gives you a vendor number y o u_ must overlay 



header, structure at the base ofj fc he segment" a n dT i fetHb he o f fset If or 1 



the sta rt 

"I t St 



t he appropriate rin keT 
of the linked rfsE an< 



Then you must get a pointer 
the invoice structure down tKe~" 



out 



checking 
the 



for the 



invoice 



, until you reach the." 
invoice. next = w 0"b. 



nu mber 
end . 



appropriate 
anil 



the 
The last 



vendor . 
charge . 



" If the ve ndor matches 
ZJorftinue 



invoice in any 



pr int 

scanning £h"i~~ list 
list is i ndicated by 
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As an example, to find invoices for vendor 357, the statement p = 
ptr( seg_ ptr ,hash_ table(7 ) ) would generate a pointer ' p* which locates 
the first invoice for a vendor with low order digit 7. The vendor 
number for this invoice can be compared to 357, and printed out if 
matched. Then, the pointer p could be adjusted to the next invoice in 
this list by coding the statement p s ptr(seg_ptr, p ->next) an d so 
on. " 

Test your program by printing out the invoice number and charges of 
all invoices for vendor number 029.- 

You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F15C>s1>include>w3.incl .pl1 . 



/* Begin w3.incl.pl1 */ 

del initiate file_ entry (char (*) , char (*), bit (*), pointer, 

fixed bin (24), fixed bin (35)); 
del code fixed bin (35); 

del bit — count fixed bin (24); 

del seg~ptr ptr ; 

del p ptr ;. 

del 1 invoice^ file_ header based (seg_ ptr), 
2 number_ofJinvoices fixed bin, - 
2 hash_table (0:9) bit (18) unaligned; 

del 1 invoice based ( p) aligned, 

2 next bit (18) , 

2 invoice — number dec (3), 
2 vendor "number dec (3), 
2 charge"" fixed dec (8,2); 

del com_err_ entry options (variable); 

del ( sysTn , 

sysprint) file; 

/* End w3.incl.pl1 */ 

For the more curious, you may wish to study 
>udd>MEDelass>F 15C>s1>set_up> put_ invoice .pll . 
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The Multics Condition Handling Mechanism 



1. Pri nt the segment >udd>MEDclass>F 15C>s1>test_any — other .pl1 (tao.pll) 
"and 1 ex ec ute the corresponding object segment. 

Examine your user stack using the 'stack 1 request of ' probe ' . 
Notice where, on the stack, the program you just executed is compared 
to the 'wall 1 laid down by default error handler. 

Using the 'signal' command, execute the following commands: "signal 
zerodivide", "signal any_ other" , "signal finish", "signal 
program^ interrupt" . How do you explain the difference in these 
four cases? 

Note: the above program is not well behaved in that it should 
have continued to signal the 'finish' condition. 

BE SURE TO DO A 'release -all' BEFORE PROCEEDING ! ! ! 



2. Print the segment ~>udd>MEDclass>F 15C>s1 >test_cleanup .pi 1 (tcu.pll ) 
and execute the corresponding object segment TWO times. BE SURE 
YOU EXECUTE IT AT LEAST TWO TIMES (more than two won't hurt, but 
is wasteful) . 

Examine the user stack using the 'stack* request of 'probe'. Notice 
the numerous occurrences of ' test — cleanup' on the stack. Now examine 
the stack using the ' tr ace_stack'~ ( ts) command. Notice the 'cleanup' 
handlers in several stack frames. (While you are at it, also 
notice that 'initialize process^' and ' defaul t_error_ handler^ ' have 
only one condition handler.) 

* Execute a "release -all". Can you explain what happened? 



3* Print the segment >udd>MEDclass>F 15C>s1 >test_finishj ,pl1 (tfl.pll ) 
and execute the corresponding object segment AT LEFST THREE TIMES. 

Signal the finish condition. 

Do a "release -all" and then repeat the above procedure using 
>udd>MEDclass>F15C>s1>test finish 2. pl1 (tf2.pl1). 
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IOCB structure 



1. Print the segment >udd>MEDclass>F 15C>s1 >ex amine_iocb .p!1 and read 
it carefully to see what it does. 

2. Execute the pr in t__attach_ table (pat) command to examine the switches 
currently attached. 



3. While in your own directory, execute the following command lines: 

io_call attach zoo vfile_ zoo 

io~call open zoo stream_Joutput 
pat 

Now execute the program >udd>MEDclass>F 15C>s 1 >ex amine__iocb and 

carefully examine the results. Notice that all pointers and entry 
points printed are in one of 3 segments. 



4. Recall that the list_reference_ names (lrn) command, if given a 
segment number , will return the pathname and reference names of 
that segment. Use this command to determine the three segments 
whose numbers were found in the IOCB. Notice especially which 
entries in the IOCB point to iox_ and which point to the I/O 
module, vfile_. Do these make sense, considering the file is 
opened for stream output? 



5. Execute the command line, ' ic_call close zoo*. Again execute the 
•pat* command. Run the prog7am, examine^ iocb , again and notice 
the different results. Can you explain what happened? If not, 
ask your instructor. 



6. Now that you have looked directly at an iocb using an overlay, 
you should try using the command that gives you the same information. 
Execute the command line 1 io call print_iocb zoo*. 



7. Using 1 io_ call print_iocb <switch>» one can easily look at the 
contents of an iocb. Try the following: delete the segment zoo, 
and then use io_ call to open zoo "keyed — sequential^ output" and to 
display the consents of the iocb. 
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Multics I/O Workshop 



Write a PL/I procedure called ( Ll uc ky num ber . p 1JJ which .. prompt s the 
user for a 6 digit number , and uses that as a ke y into an indexed file 
of lucky numbers. The file of numbers is in the segment: 

0 >udd>MEDclass>F15C>s1>lucky_nos 

The data records a re 32 characters or less in length. 

Display the records. Do not use any language- lev el I/O. Use only 
iox_ and ioa_ calls in your program. 

Test your program with the numbers 780101, 780116, and 771225. 

You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F15C>s1>include>w6.incl .pl1 

V* Begin w6.incl.pl1 */ 

>dcl iox $attach name entry (char (*) , ptr , char (*) » ptr , 

fixed bin (35)); 
del iox_$close entry (ptr, fixed bin (35)); 

del iox~$detach_iocb entry (ptr, fixed bin (35)); 
del iox - $open entry (ptr, fixed bin, bit (1) aligned, 

fixed bin(35)); 
del iox $read record entry (ptr, ptr, fixed bin (21), 

fixed bin (21), fixed bin (35)) 
del iox_$ seek_ key entry (ptr, char (256) varying, 

fixed bin (21), fixed bin (35)) 
del iox $get line entry (ptr, ptr, fixed bin (21), 

fixed bin (21), fixed bin (35)) 
del iox_ $ use r_ input external static ptr; 
del (io"a_, — 

com^err__) entry options (variable); 

del error_table_$no_ record fixed bin (35) external; 
del code "~ ™" fixed bin (35); 

del buff char (32); 

del buff ptr ptr ; 

del rec Ten fixed bin (21); 

del n — re"ad fixed bin (21); 

del number char (256) varying; 

del cleanup condition; 
del (addr, 
null , 

substr) builtin; 
/* End w6.incl.pl1 */ 
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Be sure that you provide an 1 on unit 1 for the ' cleanup * condition. 
Also, you should check for the code , error_table_$no_ record (indicating 
an invalid key) , after doing the seek keyT 
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A Storage System Workshop 



Apply the concepts discussed in Topic Ten by writing a PL/I procedure 
called 1 newsub system. pi 1 ' which, when invoked, will do the following: 

1. Determine whether or not a s ubdirec tor y called "F15C; 1 exists in 
the callers .default working directory. _If it doe s,' proceetito 
( ^£Ssk "y^below. If it does not, proceed to Cask ?j >below. If a 
^•segflfcasre or link called "F15C" exists in the calle r 1 s^defaul t worki ng 
directo ry, delete/ unlink it , notif y~tThe caller of your action , ang " 
proceed to^tep " 




2.) Since no "F15C" subdirectory exists in the caller's default working 
directory, create this direc tory. You should make sure that, besides 
the standard ACL en tr jAS^ the"" directory also has an ACL entry 
giving ^sma" access to Student 01 .».* . Re port the creation of 
this directory to the caller. 



Change the caller's working directory to the "F15C" directory, and 
notify" hh<^ ns^r of this action. * 



Compile and test out your procedure. 



(CONTINUED ON NEXT PAGE) 
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J 

You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F 15C>s1>include>w7.incl ,p!1 . 

/* Begin w7.incl.pl1 */ 



^dcl 
-del 
"del 

del 

del 
del 
del 
del 
del 

del 
del 
del 
del 



delete $path entry (char (*) , char (*) , bit (6), char (*), 

fixed bin (35)); 
he s_$ ad d_dir_ac l_entries entry (char (*) , char (*) , ptr , 

fixed bin, fixed bin (35)); 
hcs_ $append_branchx entry (char (*) , char (*) , fixed bin (5), 

(3) fixed bin (3), char (*) , fixed bin (1), fixed bin (1), 
fixed bin (24), fixed bin (35)); 
hcs_$ status_minf entry (char (*) , char (*) , fixed bin (1), 

fixed bin (2), fixed bin (24), fixed bin (35)); 
get_group — id_ $ tag_ star entry returns (char (32)); 



g et_defa ul t__wd ir_ 
chang e_wdir~ 
ab so 1 ut e_ pa t hn am e_ 



( ioa_, 
com err 



) 



error_ table__$ nomatch 
error~table_$ no en try 
addr ~" 
rings (3) 



del 1 dir_acl aligned, 
2 ¥ccess_ name 
2 dir_ modes 
2 status code 



entry returns (char (168) aligned); 
entry (char (168), fixed bin (35)); 
entry (char (*) , char (*) , fixed bin (35)); 

entry options (variable); 
fixed bin (35) external; 
fixed bin. (35) external; 
builtin; 

fixed bin (3) internal static init (4, 4, 4) 
options (constant); 

char (32) init ( "Student_01 .*.*") , 
bit (36) init ( "1 1 1 w b) , 
fixed bin (35); 



/* End w7.incl.pl1 */ 
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User Address and Name Space 



1. Write a PL/I procedure called "my _tmsr .pll " that will grompt the 
j jser for a reference name to be termJjiated .7~~ Using the appropriate 
.e jatry point in term r . duplicat e- the action of the 
~te r m in a t e si n gljLXg if n ame „com m an d ( j^e . terminate the reference name, 
but "do" not make the segment "uiffchown unless it was the last refname 
in the RNT for that segment) . The program should end by notifyi ng 
the user that the terminat ion is complete .^INCLUDE IN THE MESSAGE, 
THE ABSOLUTE PATHNAME OF TffE* SEGMENT ASSOC IATED WITH THAT REFNAME. 



Ex ec ute a simple command (ex. who, memo, pwd , list). Igst your 
program using that refer ence name as input . 



3.^-Look at the contents of ''>udd>MEDclass>F 15C>s1 >call_sub1 . pi 1 and 
5 i(f>udd>MEDclass>F 15C>s1>sub1 .pl1 . At command level, initiate the 
ob i ec t segment for the first program with the reference name "C-SJ" 
> vfcl "initiate >udd>MEDclass>F15C>s1>call_sub1 cs1") . Now execute the 
program bj£ simply typing "cs1 ". This", of course, works no matter 
what your working directory is at the time of initiation or execution. 



.^Use your " m y_ tm sr " procedure to terminate the reference name "subl". 
Again execute the call_sub1 program using the name "cs1". It should 
work exactly as it did before. 
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Writing a Command/ Active Function 



1. Wr ite a pr ocedure c all edCTpa rent .pll ' j which can function either as 
a^ommandJjSr as a<T"active function,* It is to return the entrvname 
poTlriTytr^Xthe parerrtri d irect o r y^ Ta segment supplied as an argumen t. 
That is, issuing the command "~ ~~ 

*f parent >udd>MEDclass>F15C>s1>foo 

would result in f s1 1 being output to the terminal . Used as an 
active function 

/ [parent >udd>MEDclass>F 15C>s1>foo] 
it would return the string 1 s1 1 . 

Note of course, the argument needn't be an absolute pathname. 



2. Try your command out on. various segments. 



3. Test it's ability to work as an active function by issuing the 
~ command : 

/' 

status <[ parent ??] 
where ?? is a segment in your working directory. 



4. Test, your program both as a 'command' and as an 'active function' 
giving it the wrong number of arguments. 
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You may wish to use the following declarations which are in the segment, 
>udd>MEDclass>F15C>s1>include>w9.incl .pl1 . 

/-*- Begin wQ«inol.pl -1 */ 

del cu $arg ptr entry (fixed bin, ptr , fixed bin, 

fixed bin (35)); 
del cu $af return arg entry (fixed bin, ptr, fixed bin (21), 

fixed bin (35)); 
del expand pathname entry (char (*) , char (*) , char (*) , 

fixed bin (35)); 
del complain entry variable options (variable); 

del (ioa_ , 

com~err , 

activej?nc_ err_ ) entry options (variable); 
del error_ table~$wrong_ no_ of_args external fixed bin (35); 
del nargs"" 7ixed bin; 

del ( arg_ptr , 

rtn — string_ptr ) ptr; 
del rtn_string char (max_length) varying 

based ( rtn_str ing_ptr ) ; 
del arg char ( arg_ len) based (arg_ptr); 

del max_ length fixed bin (21); 

del arg_ len fixed bin; 

del code fixed bin (35); 

del af bit (1) init ("0"b); 

del ME char (6) static init ("parent") 

options (constant); 
del entryname char (32); 

del dir_ name char (256); 
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